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STUDENT GUIDE 


INTRODUCTION 


Programming RSX-11M in FORTRAN is intended for FORTRAN programmers 
who use services of the RSX-11M operating system beyond those 
provided by the FORTRAN programming language itself. This course 
describes the various services and how to use them from a task 
which you write. 


This course is self-paced, which means that you learn at whatever 
rate is comfortable for you. 


Instead of a teacher, you have a course administrator and a 
Subject matter expert. In Some cases, the Same person can perform 
both functions. The course administrator manages the mechanics of 
the course and makes sure you have easy access to the system and 
the on-line course materials. As you finish modules, S/he records 
your progress. The subject matter expert helps you if you have a 
technical question. Before you consult the expert, however, read 
the course materials .and references in an effort to answer the 
question yourself. 
This Student Guide covers the following topics: 

e Course prerequisites 

e Course goals (and nongoals) 

e Course organization 

e Course map description 

@e Course resources 


@e How to take the course 


e Personal Progress Plotter 


STUDENT GUIDE 


PREREQUISITES 


To be prepared for this course, you must have taken the following 
DIGITAL courses, or you must have equivalent experience, 


1. RSX-11M Utilities and Commands. Specifically, you must be 
able to logon/logoff, edit files, and develop/run/debug 
programs under RSX-11M. | 


2. Programming in FORTRAN. 


COURSE GOALS AND NONGOALS 


On completion of this course, you should be able to write tasks 
which: | : : 


1. Use executive Sereckivad 

2. Perform intertask communication and coordination 

3. Perform synchronous and asynchronous I/O operations 
4. Use overlays | 


5. Use memory management facilities to communicate between 
tasks and make more effective use of available memory 


This course does not teach the following: 
1. The FORTRAN programming language 


2. The Digital Command Language (DCL) or Monitor Console 
Routine (MCR) | 


3. The program development cycle. 


STUDENT GUIDE 


COURSE ORGANIZATION 


This course is self-paced for independent’ study. The course 
material is structured in modules. Each module is a lesson on one 
or more skills required to fulfill the course goals. A module 


consists of: 


e An introduction to the subject matter of the module 


e A list of objectives, which describe what you should 
achieve by studying the module 


e A list of resources that provide reference materials’ and 
additional reading for the module 


e The module text, including explanatory text, figures, 


tables, examples, and references to readings in the 
manuals 


e Learning activities (for some modules), consisting of 
reading assignments or written exercises which are 
essential to your learning the material 


e Written and/or lab tests/exercises (bound separately) 
which you can use to measure your achievement. Solutions 
are provided for all exercises. 


The course is bound in three volumes. The first two volumes 
contain this student guide, the 18 modules (except for their 
tests/exercises), and the appendices. The third volume contains 
the tests/exercises for each module. 


COURSE MAP DESCRIPTION 


The course map Shows how each module relates to the other modules 
and to the course as a whole. Before beginning a specific module, 
it is recommended that you first complete all modules with arrows 
leading into that module. These prerequisite modules present 


material necessary to understanding the module you are about to 
study. 


If you have no- preference, study the modules in numerical order, 1 
through 10. 
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COURSE RESOURCES 


Required References 
1. RSX-11M/M-PLUS Executive Reference Manual (AA-L675A-TC) 
2. RSX-11M/M-PLUS I/O Drivers Reference Manual (AA-L677A-TC) 


3.  RSX-11M/M-PLUS Task Builder Manual (AA-L68@A-TC) 


Optional References 
1. PDP-11 Processor Handbook (EB-19492-20/81) 
2. j.>FORTRAN IV User's Guide 
3. FORTRAN IV-PLUS User's Guide 


4. FORTRAN 77 User's Guide 
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HOW TO TAKE THE COURSE 


Because this is a self-paced course, you determine how much time 
to devote to each subject. You can pass quickly over familiar 
topics. You can spend more time on topics which are of interest 
to you, or which you can use often in your job, and less time on 
topics which have little use in your job. 


Each time you are ready to begin a new module, first read _ the 
introduction. and the objectives. If you feel that you already 
understand the material in the module, you can go immediately to 
the tests/exercises for that module. If you don't understand much 
of the material, read the module. If you understand some of- the 
concepts but not others, just look over the program examples for 
the concepts you understand. Read the text and study the examples 
for concepts you don't understand. The text explains new concepts 
and refers you to related readings in the manuals. The program 
examples provide working examples which show you how to apply the 
concepts. ., 


Some of the readings in the manuals are required and others are 
optional. Required readings are contained in learning activities 
and are indented to set them apart from the module text. These 
readings are required because they cover material not otherwise 


covered in this course. The optional readings are mentioned 
within the module text and are designed to help you in two ways. 
First, they teach you more about a given topic. Second, they 


offer another explanation in case you have trouble understanding 
the explanation in this course. 


In addition, you will need the manuals to look up the specifics 
involved in invoking the various services. This is especially 
true for the executive directives. 


Keep the module objectives in mind. If a skill is listed as an 
objective, be sure to master it. Later modules may depend on this 
skill. 


The module text contains many example programs to show you how to 
use the skills you are learning. All of the example programs in 
this book should be available on-line. The standard location for 
these files is UFD [282,1] on your system disk. Check your system 
and if the files are not located there, check with your course 
administrator to find out where they are located. 
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Do not modify the files in UFD [2@2,1] or in their original 
location. Instead, copy the files you plan to use to your own UFD 
and use them there. In that way, the original files in  UFD 
[202,11] will remain intact for other students. 


Each example program contains the following: 
e Source code 
e A sample run session: 


e Bulleted items which are described in the text. 


The source code contains the name of the file which contains’ the 
code on-line. Following this is a brief description, telling what 


the example does. Any special compile and task-build 
instructions, and any Special install and run instructions follow 
this. Only special, nonstandard instructions are included. The 


code itself includes line comments plus some additional comments. 


The sample run session shows what happens during a typical run of 
the task. Any special install and run instructions are shown in 
the run session. 


The bulleted items match the example notes in the text, which 
describe the code in more detail. Study the examples and the 
notes that describe them carefully. 


In the module on Using File Control Services, many of the examples 
create output files. A dump of any created file follows the run 
session. The file dumps were created using the DMP utility. 


If the examples are available on-line, compile and _ task-build 
them, and then run them. This will help you to understand the 
examples better. Many of the tests/exercises ask you to make 
Minor changes to existing examples, and then run them again. Do 
the tests/exercises for a module in the Tests/Exercises book only 
after you have done all of the reading and have run the example 
programs. If you prefer, you can do them as soon as you cover the 
necessary material in the module. 


The same Tests/Exercises book is used in this course and _ the 
Programming RSX-11M in MACRO course. Do all tests/exercises 
except those which specifically say "in MACRO". All exercises 
have solutions in the Tests/Exercises book. In addition, any 
solutions involving programs should be available on-line, in  UFD 
[202,2]. Compare these solutions to your own. 
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If you have mastered the module objectives, ask your course 
administrator to record your progress on your Personal Progress 
Plotter. You will then be ready to begin a new module. If you 
haven't yet mastered the module objectives, return to the module 
text for further study. 


With a self-paced course, it is impossible to give a schedule that 
applies to all students. The amount of time that students spend 
on a module depends on both their experience and their interest in 
the topics in that module. Use Table 1 as a guide when you set 
your schedule. 


10 


STUDENT GUIDE 


In addition to the 18 modules, the Student Workbook contains 
several appendices. These are: 


Appendix A - Glossary 


Appendix B - Conversion Tables. This appendix contains a 
table for converting between decimal and octal, and among 
words, bytes, and memory blocks. It also contains a table 
for converting from active page registers (APRS) to virtual 
addresses. 


Appendix C —- FORTRAN/MACRO-11 Interface, This appendix 
contains an explanation of the techniques which you should 
use to write a FORTRAN callable subroutine in MACRO. It also 
explains how to call such a subroutine from FORTRAN. 


Appendix D - Privileged Tasks. This appendix contains a 
description of the various types of privileged tasks 
supported under RSX-11M, and how to create them. 


Appendix E - Task Builder Use of Psect Attributes. This 
appendix contains a description of the effect of Psect 
attributes on how the Task Builder collects together 
scattered occurrences of program sections. 


Appendix F - Additional Shared Region Topics. This appendix 
contains several additional shared region topics. They are: 
overlaid shared regions, referencing multiple regions from a 
single task, interlibrary calls, and cluster libraries. 


Appendix G - Additional Example. This appendix contains’ the 
source code for any program examples which are required for 
the Tests/Exercises but are not included elsewhere in the 
Student Workbook. These examples should also be available 
on-line, under UFD [2@2,1]. They are included here in case 
they are not available on-line on your system. 


Appendix H ~- Learning Activity Answer Sheet. This appendix 
contains the solutions to any Learning Activity questions in 
this course. After you do a Learning Activity, check your 
answers against those provided. 
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Table SG-1 Typical Course Schedules 


More Experienced Less Experienced 

Module > Student Student 

1. Using System 2.8 hours 3.8 hours 
Services 

2. Directives 5.@ hours 7.5 hours 

3. Using the QIO 4.9 hours 6.9 hours 
Directive 

4. Using Directives 5.@ hours 7.5 hours 
for Intertask 
Communication 

5. Memory Management 2.9 hours 3.8 hours 
Concepts 

6. Overlays 5.@ hours 7.5 hours 

7. Static Regions 4.5 hours 7.9 hours 

8. Dynamic Regions 4.5 hours 7.8 hours 

9. File I/0 2.@ hours 3.9 hours 

19. File Control 6.@ hours 9.8 hours 
Services 
Totals 49.8 hours of 66.5 hours of 

Study and lab study and lab 
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PERSONAL PROGRESS PLOTTER 


DATE DATE TIME SIGN-OFF 
MODULE STARTED | COMPLETED SPENT INITIAL 


USING SYSTEM 
SERVICES 


DIRECTIVES 


USING THE QIiO 
' DIRECTIVE 


USING DIRECTIVES 
FOR INTERTASK 
COMMUNICATION 
MEMORY 
MANAGEMENT 
CONCEPTS 


8. DYNAMIC REGIONS 
FILE I/O 


9. 

10. FILE 
CONTROL 
SERVICES 
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USING SYSTEM SERVICES 


INTRODUCTION 


RSX-11M provides system services which perform many operations 


commonly 


needed by user-written application programs. Use of 


these services can: 


Improve the efficiency of your tasks by reducing the size 
and execution time 


Decrease the time it takes to code and debug your tasks 
Increase the reliability of your task 
Provide you with controlled access to system features 


Improve the overall performance of your system 


This module discusses what services exist and how they are called 
from a task. 


OBJECTIVES 


Identify the facilities provided through system services. 


List the various system libraries and the facilities they 
provide. 


RESOURCES 


RSX-11M/M-PLUS Executive Reference Manual, Chapter 1 
FORTRAN IV User's Guide, Appendix B 
FORTRAN IV-PLUS User's Guide, Appendix D 


FORTRAN-77 User's Guide, Appendix D 
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WHAT IS A SYSTEM SERVICE? 


An RSX-11M system service is a function or service performed for a 
running task during the task's execution. The software which 
provides the service is either in the Executive or in other system 
supplied code. 


WHY SHOULD YOU USE SYSTEM SERVICES? 


To Extend the Features of Your Programming Language 


System services offer you additional features not inherently part 
of your programming language. Examples of this are: 


e Accessing shared resources in a properly synchronized way 


e Coordinating multiple tasks 


e Controlling memory allocation and mapping 


e Interacting with the Executive 


To Ease Programming and Maintenance 


DIGITAL provides the code to perform these services, hence less 
time is needed for the user to develop working programs. The 
supplied code has a well defined modular structure which eases 
user design for his programs. 


The code for system services is well debugged. This makes it 
easier to debug and maintain programs, since there are fewer 
potential points of failure and only the user written code needs 
to be debugged. When maintenance is required in the code for the 
supplied system services, patches are released by DIGITAL. with 
clear-cut installation procedures. 
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To Increase Performance 


The supplied code to perform system services is generally written 
in MACRO-11 which assures minimum execution time. It is often 
possible to share the code among several different tasks, with 
minimal additional overhead. This can result in any or all of the 
following performance gains: 


Increase in your task's throughput 

Increase in your system's throughput 

Increase in memory usage efficiency on your system 
Decrease in your task's size 

Increase in available space on mass storage volumes 


WHAT SERVICES ARE PROVIDED? 


The system services can be divided into a number of classes. For 
each, a few examples are mentioned to give you a feeling for the 
kinds of services available. 
Note that a number of the services provided to tasks parallel 
those provided to operators through DCL commands. 
System and Task Information 
You can obtain information from the system. For example, you can: 
e Obtain information about your task 
- its priority 
- its logical unit (LUN) assignments 
e Obtain information about a partition on the system 
- its base address 


~ its length 


e Obtain the current time and date 
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Task Control 


You can start up and stop tasks, and alter task states. For 
example, you can: 


Request another task to run 

Abort a task 

Suspend or resume a task 

Alter the running priority of an active task 


Task Communication and Coordination 

You can create a set of tasks that communicate with one another 
and coordinate the interaction of the tasks. For example, you 
can: 


e Send data from one task to another 


e Have one task notify other tasks that an event has 
occurred (e.g., that a job has been completed) 


e -Have one task pasS a command to another task and have it 
obtain an indication from the other task about the status 
of the execution of the command. 


I/O to Peripheral Devices 


You can interact with peripheral devices on your’ system. For 
example, you can: 


e Perform special I/O functions which cannot be accomplished 
by FORTRAN READ or WRITE statements such as reading from a 
terminal with the NOECHO feature invoked. 


e Attach a device for exclusive use by a task 


e Read or set variable characteristics of a device (e.g., 
for a terminal - baudrate or hold screen mode) 
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Memory Use 

You can use system services to control the amount of memory your 
task uses or to permit several tasks to share an area of memory. 
For example, you can: 


e Run a task in less memory than its total size, by using 
overlays to-load pieces of the program at any one time 


e Allocate space in memory for a temporary work buffer, and 
then return that space to the system when the task is 
finished using it 


e Share a data area in memory among several tasks 


e Share a single copy, in memory, of a commonly used 
‘Subroutine, among several tasks 


OTHER SERVICES AVAILABLE 


You can use system services to perform often needed functions. 
For example, you can: ; 


e Convert between Radix-5@ and ASCII format 
e Get the date in dd-mon-yr format or as three integers 


These services are generally supplied as subroutines located in 
the system object library (LB:[{1,1]SYSLIB.OLB). 
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HOW SERVICES ARE PROVIDED 


When a system Service is needed in a task, it is called via the 
CALL statement just as for any other subroutine. Services are 
provided using two different methods: 


1. The Executive is invoked by the task to perform. the 
service (an executive directive) 


2. The code to perform the service is placed directly into 
the task 


Executive Directives 


Figure 1-1 shows how the first method works. The following steps 
are involved: 


@ The user task makes a service request and invokes’ the 
Executive | 


@ The Executive takes control and performs the service 


@ The Executive returns control to the user task, at the 
Statement following the service request. . 


Figure 1-2 shows a more complex version of the first method. In 
this case task A and task B use a system service to interact 
through the Executive. | 


Task A starts up and at some point needs task B to do some _ work; 
possibly a calculation. Task A sends the data to task B, requests 
task B to run, and then waits until task B sends back the answer. 
Task B starts running, performs the calculation, and then sends 
the answer back to task A. Task B also notifies task A that’ the 
job is finished. Task A then starts up again and uses the answer. 
The steps outlined above for method one would actually be used a 
number of times in this example. 
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Figure 1-1 Using Executive Directives to Service a Task 
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Figure 1-2 Using Executive Directives to Receive Services 
From Other Tasks 
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Code Inserted into Your Task Image 


The second method of providing system services is illustrated in 
Figure 1-3. The code to perform the service is inserted directly 
into the user task. For system subroutines, the subroutine call 
results in a transfer of control to the subroutine code, located 
in another part of the user task. 


Certain services must be provided by invoking the Executive. Any 
service which involves synchronization or access _ to_ shared 
resources must be coordinated by the Executive. For example, if a 
request activates another task, the Executive must enter the task 
in the active task list, which sets the task up to compete for 
memory space and then CPU time. It is much easier to have the 
Executive coordinate all the tasks, rather than require that’ each 
task check with every other task before using a shared resource, 
Also, any activity that involves communication or coordination 
among multiple tasks usually must be performed by the Executive. 


Placing the code in the user task is appropriate for a_ service 
which is performed independently by.a task. For example, if a 
task converts an ASCII decimal value which is input at a_ terminal 
to a Radix-5@ value for internal use, there is no need for the 
Executive to coordinate that activity. It does not affect shared 
resources or other tasks. 


If a service can be provided without need for the Executive, and 
that service is needed often by a number of different tasks, it is 
possible to share one copy of the code among several tasks. Using 
special techniques, often used subroutines can be collected and a 
Single copy of each subroutine can be shared in memory among 
several tasks. The procedure for producing and using a shared 
collection of subroutines, called a resident library, is discussed 
in the Static Regions module of this course. 


Some of the services covered in this course are provided by making 
special requests when you task-build your task. In some cases, 
the Task Builder transparently places code directly in your’ user 
task. In other cases, it sets your task up in a special way to 
provide the service. We will discuss the techniques for accessing 
services with the Task Builder in later modules. 
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Code Inserted into Your Task Image 
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AVAILABLE FILE AND RECORD ACCESS SYSTEMS 


There are two file and record access systems available under 
RSX-11M, File Control services (FCS) and Record Management 
Services (RMS). Both offer an:-interface between tasks and the 
Files-1ll structure used to maintain disk directories and files. 


FCS is the standard access system supplied with RSX-11M. Many of — 
the utilities (e.g., PIP, EDT, and the Task Builder) use FCS for 
their file interface. RMS offers all of the FCS’ functionality 
plus additional capabilities not available with FCS, such as 
indexed files and more sophisticated file sharing. 


While it is transparent to the FORTRAN user, all READ or _ WRITE 
statements ultimately result in calls to various FCS or RMS 
subroutines. 


SYSTEM LIBRARIES 


Table 1-1 contains a list of the libraries which are used during 
program development of a task using system services. They are 
usually located in LB:[1,1]. SYSLIB.OLB is the system object 
library searched by default by the Task Builder. 
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Table 1-1 Standard Libraries 


Langages Version of Contents Notes 

Using FORTRAN Using 

Library Library 

SYSLIB.OLB FORTRAN Executive directive Default object 
calls for FORTRAN library for 


Task Builder 
FCS subroutines 


Other file access 
routines 


Command retrieval 
and parsing 
routines 


Assorted conversion 
routines, arithmetic 
routines, memory 

management routines 


RMSLIB.OLB FORTRAN RMS subroutines 
. indirectly 
used 
FOROTS.OLB FORTRAN IV FORTRAN IV Object Optional soft- 
Time System (OTS) ware may be 
included in 
SYSLIB.OLB 
F4POTS.OLB FORTRAN IV-PLUS FORTRAN IV-PLUS OTS Optional soft- 
FORTRAN-77 FORTRAN-77 OTS ware may be 
included in 
SYSLIB.OLB 
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One or the other of the last two libraries must be included when 
task-building a FORTRAN task unless, as_ the note states, the 
libraries are included in SYSLIB.OLB. as 


Check with your system manager to determine what additional 
software may be included in SYSLIB.OLB at your site. 


Table 1-2 contains a list of the shareable resident libraries 
which may also be on your system depending upon your installation. 
You will learn how to use these resident libraries in Module 7, 
the Static Regions module. Check with your system manager to find 
out whether the preferred method of including these routines is 
through linking the code into your task image or through using the 
resident libraries. 


Table 1-2 Resident Libraries 


Resident Routines 

Library Extracted From Notes 

FCSRES.TSK SYSLIB.OLB Generally contains most 
FCS routines 

FORRES. TSK FOROTS. OLB May contain all or 

F4PRES.TSK F4POTS. OLB some FORTRAN OTS routines 

RMSRES. TSK RMSLIB. OLB Full-functionality RMS 
resident library 

RMSSEQ. TSK RMSLIB.OLB RMS resident library for 


sequential access only 


Now do the Tests/Exercises for this module in the Tests~ and 
Exercises Book. They are all written problems. Check your 
answers against those provided in that book. 


If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, return 
to this module for further study. 
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DIRECTIVES 


INTRODUCTION 


As stated in the previous module, system services can be _ placed 
into two groups: ; 


e@ Those which are handled entirely by the user task (via the 
subroutine representing the service) 


e Those which require the intervention of the Executive 
The services in the second group are known as executive directives 


(directives). This module discusses the services available as 
directives and how to make various directive calls. 


OBJECTIVES 


l. To write programs in FORTRAN which use directives 


2. To use information returned by the Executive to perform 
error checking 


3. To use event flags and ASTs with directives 


RESOURCES 


1. RSX-11M/M-PLUS Executive Reference Manual, Chapters 1 and 
2 plus specific directives in Chapter 5 


2. FORTRAN IV User's Guide, Appendix B 
3. FORTRAN IV-Plus User's Guide, Appendix D 


4. FORTRAN 77 User's Guide, Appendix D 
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INVOKING EXECUTIVE DIRECTIVES FROM A USER TASK 


Directive Processing 


When an executive directive is called from a FORTRAN task, a 
standard CALL is generated with an argument list containing each 
argument in the CALL. When the Task Builder builds the task, the 
code for the subroutine which invokes the directive is placed in 
the task. (The subroutines are found in LB:[1,1]SYSLIB.) 


At execution time this code generates a Directive Parameter Block 
(DPB) and then pushes the DPB onto the stack. The DPB contains 
all of the information needed by the Executive to perform the 
requested service. This includes a Directive Identification Code 
(DIC) which identifies which directive is being requested and the 
length of the DPB. The length is included because the length can 
vary depending on what directive is being called. 


At execution time, the following steps occur: 


e The DPB is pushed onto the stack and a trap is made to’ the 
Executive. 


e A dispatcher routine (part of the Executive) receives’ the 
DPB and determines which directive has been requested. 


e The dispatcher routine enters the Executive at the 
appropriate point, depending on the DIC, and the Executive 
executes the code for the directive (note that the code for 
the directive actually resides in the Executive, not in the 
task). 


e The Executive sends a Directive Status Word to the task and 
then returns control to the user task. 


Most directives pass control back to the user task at completion 
of the directive. Certain directives by their nature do not 
return to the user task. For inStance, the Exit Task directive 
causes the task to EXIT. For the Exit Task directive and other 
directives of this type, control passes back to the user task only 
if an error occurs: in issuing the directive. 
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Functions Available Through Executive Directives 


Table 2-1 lists many of the Executive directives which are 
available on your system. For a complete list of the directives 
under each group, see section 5.1 (on Directive Categories) in the 
RSX-11M/M-PLUS Executive Reference Manual. 


This module, along with later modules on Using the QIO Directive, 
Using Directives for Intertask Communication, and Dynamic Regions 
introduce many of the functions which are available. No attempt 
is made to go over every executive directive. However, at the end 
of this course, you should know how look up any directive in the 
manual and invoke it. Each directive is documented individually 
in Chapter 5 of the RSX-11M/M-PLUS Executive Reference Manual. 
The directives appear there in alphabetical order by MACRO-11 
name; the FORTRAN CALL name for directives is similar to the 
MACRO-11 name and is also included in the list. A condensed list 
of the MACRO and FORTRAN directive names also exists in Table 1-l 


in section 1.5.2. To find the page reference for a particular 
directive, look under "CALL" in the index. 
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Type 


Task Execution 
Control 


Task Status 
Control 


Informational 


Event- 
Associated 


Trap-Associated 


I/O and 
Intertask 
Communications 


Memory 
Management 


Parent/ 
Offspring 
Tasking 
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Table 2-1 


Types of Directives 


CALL Name 


ABORT 
EXIT 
REQUES 
RESUME 
RUN 
START 
SUSPND 
STOP 
USTP 


ALTPRI 
DISCKP 
ENACKP 


GETPAR 
Several 


CLREF 
CRGF 
ELGF 
MARK 
WAIT 
READEF 
READEF 
SETEF 
WAITFR 


SREA 
ASNLUN 
QIO 
WTQIO 


RECEIV 
SEND 


CRRG 
MAP 


EXST 
SPAWN 
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Description 


Abort task 
Exit task 
Request task 
Resume task 
Run task 

Run task 
Suspend task 
Stop task 
Unstop task 


Alter priority 
Disable checkpointing 
Enable checkpointing 


Get partition parameters 
Get time parameters 


Clear event flag 

Create group global flags 
Eliminate group global flags 
Mark time 

Mark time 

Read all event flags 

Read extended event flags 
Set event flag 

Wait for single event flag 


Specify requested exit AST 
Assign LUN 


Queue I/O request 
Queue I/O request and wait 


Receive data 
Send data 


Create region 
Map address window 


Exit with status 
Spawn task 
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The Directive Status Word (DSW) 


_ Upon completion of directive processing, the Executive returns a 
code in the Directive Status Word (DSW) which gives the status of 
the request. In order to examine the contents of the DSW and 
hence determine success or failure, a specific argument must be 
included in the CALL for the directive. This argument is always 
the last argument in the list. While this argument is optional, 
it should always be included since examining the DSW is the only 
way to determine the success or failure of a directive. The 
system does not look on a directive failure as an error; hence it 
is up to the user to check the DSW after a directive CALL. The 
variable name "IDSW" is frequently used for the DSW; it must _ be 
an integer variable. 


Successful completion is usually indicated by a DSW value of +l. 
A negative value indicates an error. Different negative values 
correspond to different reasons for errors. These values and 
their general meanings appear in Appendix B of the RSX-11M/M-PLUS 
Executive Reference Manual and in the RSX-11M/M-PLUS Executive 
Reference Manual. Specific error values and any Special meanings 
are documented with each executive directive call in Chapter 5 of 
the RSX-11M/M-PLUS Executive Reference Manual. 


See Example 2-1 for an illustration of how to use the DSW. 
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Sample Program 


Example 2-1 illustrates the use of the Request Task and the Exit 
Task directives. The directives are given below, along with a 
description of their functionality: 

The Exit Task Directive 

- format: CALL EXIT - this CALL has no arguments 


- used to make a task inactive and to free up the _ system 
resources it uses 


The Request Task Directive 


- format: CALL REQUES(TASKNM, , IDSW) where TASKNM is’ the 
name of the task to be requested 


- used to request the specified installed task 


- this directive offers the same functionality as the DCL 
RUN command for an installed task 


Each program example in the course contains the following: 


e Source code 
e A sample run session 
e Bulleted items which are described in the text 


See the Student Guide for additional information on how to use the 
examples. 
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The following comments are keyed to Example 2-1. 


If the appropriate OTS library has been included in 
SYSLIB, the reference to the OTS library is dropped. 


Invoke the Request Task directive. Note that the six 
character (or less) task name must be provided in Radix-59@ 
format. This is accomplished by using the R_ (Radix-5@) 
data type in the DATA statement. (Radix-5@ is a method of 
representing a limited set of ASCII characters, such that 
three characters can be packed into a single PDP-11 word.) 
The task name must be the installed name (...PIP), not 
just PIP. 


The task is always assumed to be six Radix-5@ characters; 
hence you should always pad a name of less than six 
characters with trailing blanks. For instance, TASKNM 
6R/ABC / should be used rather than TASKNM 3R/ABC/. 


See Appendix A of the Language Reference Manual for 


additional information on Radix-5@. 

The only case in which control will return to the user 
task after a CALL EXIT is when an error occurred in 
issuing the directive. 

In case of an error, display a message and the DSW value. 
A run session is provided for each example program. Note 


that the PROGRAM name is REKWST, not REQUES. REQUES 
cannot be used because it is the name of a directive. 
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FROGRAM REKWST 
C FILE REQUES.»FTN 


C This task disrelays e@ messesey reauests FIFy and 
CQ then exits 


C Task-build instructions? 


C If your LAiCislISYSlLik.OLB does mot contain the 


CC FORTRAN ObJect Time Systems then vou must 
C srecify the arrrorriate obJect Library 


C With FORTRAN IV; 

C LINK/MAF REQUES»LES Cis LIFOROTS/LIBRARY 

C With FORTRAN IV-PLUS and FORTRAN~77 

C SLINK/MAF/CONE FRPP REQUESsLES Cl» LIF4POTsS~— 


C ~2/LIBRARY 
C | /COMEIFFPF includes sreace in the task 


C ! header for saving the stsete of the 
C i floating eoint errocessor, 


° 
C ata statement for RADSO task name 
NATA TASKNM /6R...+PIF/ 
CG Yiselay startur text 
WRITE (S950) 
Le) FORMAT (° REQUES HAS STARTED AND WILL REQUEST FIF*) 
[ Reauest FIF 
CALL REQUES CTASKNMs » TSW) 
( Check for Directive error 
IF ¢I0SW .NE. 1) GOTO 1000 
CO No errors $0 @xit 
CALL EXIT 
C Error code. Dliselay error messase and then exit. 
1000 WRITE (321010) Tnsw 
LOLO FORMAT (”% ERROR REQUESTING TASK. T0SW = ’sTS) 
CALL EXIT 
ENT 


Rur Session 


“RUN REQUES 
REQUES HAS STARTED AND WILL REQUEST FIF 
IPS OZ 


Example 2-1 Requesting a Task From Another Task 
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Example Using Other Directives 
The following directives are used in Example 2-2. 
Suspend Task (CALL SUSPND) 
e Used to suspend the eautns task 
e The task can be resumed by another task issuing a _ resume 
task directive or by an operator using the DCL CONTINUE 
command. 
Alter Priority (CALL ALTPRI) 
e Alters the running priority of an active task. 
Disable Checkpointing (CALL DISCKP) 
e Disables checkpointing for a checkpointable task. 
Enable Checkpointing (CALL ENACKP) 
e Enables checkpointing again after a DISCKP directive. 


Extend Task (CALL EXTTSK) 


e Modifies the size of the task by an increment or decrement 
of 32-word blocks. 
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Example 2-2 shows the use of a variety of directives. See the run 
demonstration below the source code. The following comments are 
keyed to the example. Items 2,3,5 and 7 refer to the run’ session 
following the program listing. 


Task suspends itself. This allows the operator to use the 
DCL SHOW TASKS/ACTIVE command to examine the task 
parameters. 


Note that the task is loaded at addresses 91123698(8) to 
91170190(8). SPN means the task is suspended. 


The operator must use the DCL CONTINUE command to’ resume 
the task. . 


Suspend again after disabling checkpointing and altering 
the running priority. 


Note the change in PRI (running priority). CKD in the 
output from the DCL command SHOW TASKS/ACTIVE indicates 
that checkpointing has been disabled. 


Suspend again after enabling checkpointing, altering the 
priority back to 58@(18), and extending the task. 


Note the change in priority. Note also that the task was 
checkpointed and is now loaded at addresses 91123698(8) to 
91219190(8). This is a task size of 64380(8) bytes, 
compared to 44388@(8) bytes before. The extend is for 
200(8) blocks, where each block is 19@(8) bytes long, 
meaning 28000(8) bytes extra. See Appendix B_ for a 
conversion table for bytes to blocks and of octal _ to 
decimal. 


91179198 (8) 1218190 (8) 
-$1123698 (8) -91123698 (8) 
443008 (8) 64308 (8) 


43 


C 


Example 2-2 


DIRECTIVES 


PROGRAM MISC 
FILE MISC.FTN } 


This task uses some miscellaneous Executive directives 


> to susrend itselfy alter its running rriorityy disable 


and enable checkrointings and extend its task size. 
Task-build instructions? 


LINK/CHECKFOINT/MAFP MISCy»yLBS Cis LAIFOROTS/LIBRARY 
since the task must he checkrointable to disable 
checkrointing and to extend its size. 


Install and Run instructions? 


Install the task. Then Run it to start it ur. 
The task will susrend itself several different 
times. Each times use the command 

SHOW TASKS? MISC/ACTIVE/FULL (MCR ATL MISC) 

to examine the chanses. Use the command 
CONTINUE MISC (MCR RESUME MISC) 

to resume the task. 


INTEGER ['SWeTRCTY 
CALL SUSPNOCOSW) ! Susrend to ellow check 
fo uU6af status 
I 


IF (nSW.LT.O) GOTO 1010 Branch on directive 


! error 
Make some chanses and then susrend asain 
CALL DISCKF CUSW) ! Tlisahle checkerointins 
IF (oiSW.LT.O)} GOTO 1020 
CALL ALTFRICs10OsTSW) | Alter running eriority 
IF (USW.LT.O) GOTO 1030 
CALL SUSPNICOSW) ; ! Susrend to allow check. 


tv hUof status 
IF (”SW.LT.O)} GOTO 1040 
Make some other changes and then susrend asain 


CALL ENACKF (nSwW) ! Reenable checkrointings 
IF (OSW.LT.0O) GOTO 1050 
CALL ALTFRI(¢» »lSW) ! Return eriority to 

! 6 goristinal 


IF (USW.LT.O) GOTO 1060 

CALL EXTTSK¢C*200+0NSW) 9! Extend task size ty 
| 6 §©6200¢8) blocks 

IF (USW.LT.O>) GOTO 1070 


CALL SUSFNIECOUSW) ! Susrend asain 
IF (USW.LT.O) GOTO 1080 
CALL EXIT ! Exit 


> Error handling 


10 WRITE (S91015) SW 

15 FORMAT (° ERROR ON 1ST SUSPENI. USW = ’»IS> 
GOTO 1100 

20 WRITE (S91025) DSW 


Using Some Miscellaneous Directives (Sheet 1 of 
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LO25 FORMAT (’ ERROR ON DTSABLE CHECKFOINTING. DSW = ” 
Ly IS) 
GOTO 1100 

L030 WRITE (S91035) 0SwW 

L035 FORMAT (¢% ERROR ON 1ST ALTER PRIORITY. DGW = “» 
LIS) 
GOTO 1100 

1040 WRITE (Se1l045) nsw 

1O4S FORMAT ¢°’ ERROR ON 2NI) SUSFENT. DSW = “y»IS) 
GOTO 1100 


LOS WRITE (Sv1l035) 0SwW 

LOSS FORMAT (€° ERROR ON ENABLE CHECKPOINTING. DSW = ¢ 
Le IS) 
GOTO 1100 

L060 WRITE (Sv1065) DSW 

LO4S FORMAT (”% ERROR ON 2Nt ALTER FRIORITY. DSW = 7» 
LIS) 


GOTO 1100 
L070 WRITE (S91075) SW 
LO7S FORMAT ¢(° ERROR ON EXTENT TASK. DSW = “TS) 
GOTO 1100 
1080 WRITE ¢(S»91085) [sw 
LO8s FORMAT (€’ ERROR ON SRO SUSPEND. DSW = %’»TS)> 
L100 CALL EXIT 
ENT 


Rum Session 


SINS MISC 
“RUN MISC 
“SHOW TASKS/ACTIVE FULL MISC | 
2) MISC 067250 GEN 070310 O1123600-01170100 PRI ~- SO. DPRI - S50, 
STATUS? SFN ~-FMD 
TI - TT113 TOC ~ oO. BIO ~ O. EFLG —- 900000 000000 FS ~ 170000 
FC ~ 001640 REGS O-6 600001 001242 001242 000000 001432 003572 001242 
“CONTINUE MISC 
“SHOW TASKS/ACTIVE FULL MISC” 


6 MISC 067250 GEN 070310 01123600-01170100 FRI - 10. OFRI - So, 


STATUS? CKIt SPN -FMI 
TI - Tit? IOC ~ Oo. BIO ~ OO. EFLG - 000000 000000 FS ~- 170000 
PO - 001640 REGS 0-6 003626 001242 001242 000000 001432 003572 001242 
SCONTINUE MISC 
*SHOW TASKS/ACTIVE FULL MISC 
MISC 067250 GEN 070310 01123600-01210100 PRI ~ SO. ORRI ~ SO. 
STATUS? SFN —FPMII 
TI ~ TT11? %gToOC - 0. BIO - 0. EFLG ~- 000000 000000 FS ~- 170000 
PO ~- 001640 REGS O-6& 003626 001242 001242 000000 001432 003572 001242 
“CONTINUE MISC 
@SHOW TASKS/ACTIVE FULL MISC 
ATL ~~ Task not active 


Example 2-2 Using Some Miscellaneous Directives (Sheet 2 of 2) 
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Run Time Conversion Routines 


As mentioned earlier, the system maintains task. names, partition 
names, and certain other data in Radix-5@ format in order to save 
space. There are times when conversions between ASCII and 
Radix-5@ format need to be performed at run time. For example, 
you can modify Example 2-1 (REQUES.FITN), So an operator can _ type 
in the task name at run time. This ASCII name would have to be 
converted at run time to Radix-5@ format. The function RAD5Q@ or 
the subroutine IRAD5@ is used to perform the conversion. The code 
segment shown below illustrates the use of the function RAD5@: 


DIMENSION TASKNM (2) 
READ (5,1) TASKNM 
1 FORMAT (2A4) 
CALL REQUES (RAD5Q@ (TASKNM) , , IDSW) 


If the Get Task directive (CALL GETTSK) is used to retrieve task 
information, the task name and partition name are returned in 
Radix-5@ format. If you wish to display these, you need _ to 
convert them to ASCII format. The subroutine R5@ASC is provided 
for this purpose. The program shown below illustrates the use of 
the R5@ASC subroutine: 


DIMENSION IBUFF (16) 

CALL GETTSK(IBUFF) 

CALL R5Q@ASC(6,IBUFF(1) , TASKNM) 
CALL R5@ASC (6, IBUFF (3) , PARTNM) 
WRITE (5,1) TASKNM 

WRITE (5,2) PARTNM 


Hi FORMAT(' TASK NAME IS ',A6) 
2 FORMAT(' PARTITION NAME IS ',A6) 
END 


46 


DIRECTIVES 


NOTIFYING A TASK WHEN AN EVENT OCCURS 


Often a task needs to know when an event has occurred. The event 
may have occurred within another task; for example, when the task 
has completed a requested function. The event may instead have 
occurred within the system; for example, when a requested I/O 
operation is completed. There are two methods for implementing 
synchronization, event flags and asynchronous system traps. 


Event Flags 


There are three types of event flags: local, global (or common), 
‘and group global. Ninety-six event flags are made available to 
tasks, each with a unique number (1(18)-96(19)). 


Local event flags are provided for each task. There are 32(19@) 
local event flags, numbered 1(18)-32(18). These flags are used to 
synchronize a task with an Executive service, such as an I/O 


transfer. One task cannot reference another task's local event 
flags, so they cannot be used to synchronize tasks with one 
another. Local event flags 25(18)-32(18) are reserved for system 


use and hence should not be used by a user task. 


Global or Common event flags are provided for synchronization 
among different tasks. There is one set of 32(18) global event 
flags for the system numbered 33(19)-64(18). These flags can be 
referenced by any task. Global event flags 57(10)-64(10) are 
reserved for system use and should not be used by user tasks. 


NOTE . 

There is no way to protect against other 
tasks using global event flags. Great care 
must be taken to ensure that global event 
flags aren't used at the same time by several 
different users. Check with your’ system 
manager before using any global event flag to 
insure that it is not used for some. other 
purpose. 
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There are only 32(18@) global event flags available system-wide. 
If additional event flags are needed, another set of event flags 
can be created for synchronization among different tasks. 32(19) 
group global event flags, numbered 65(18)-96(18), can be created 
for any UIC group number. These event flags can be referenced by 
any task running under the correct group number. Hence, they can 
be used to synchronize tasks running under that group number, and 
offer an additional advantage in that they cannot be referenced by 
tasks running under other group numbers. 


Group global event flags are created using the DCL SET GROUPFLAGS 
CREATE (FLA /CRE in MCR) command or the Create Group Global Event 
Flags (CRGFS$) directive. When users in a group don't need them 
anymore, the group global event flags can be marked for deletion 
using the DCL SET GROUPFLAGS DELETE (FLA /ELIM in MCR) command or 
the Eliminate Group Global Event Flags (ELGFS$) directive. After 
that, when all active tasks in the group have finished using them, 
the group global event flags are eliminated. 


Using Event Flags for Synchronization 
LEARNING ACTIVITY 2-1 


Read section 2.2 (on Event Flags) in the 
RSX~11M/M-PLUS Executive Reference Manual. 
Pay particular attention to the examples. 
This section covers how event flags can be 
used for synchronizing tasks. When you have 
finished reading the material, answer the 
following questions. The answers are 
provided in Appendix G. 


Questions: 

1. In Example 1 in the reading, how can Task 
B do some work while waiting for event 
flag 35 to be set by Task A? 

2. What would happen in Example 2 if a local 
event flag (e.g., 1) were used instead of 
a common event flag? 


3. Why is a local flag satisfactory in 
Examples 3 and 4? 


48 


DIRECTIVES 


Examples of the Use of Event Flags for Synchronization 


Examples 2-3 and 2-4 show the use of event flags to synchronize 
two tasks. WFLAG creates the group global event flags for the 
group. It then clears event flag 65(198) and waits for that flag 
to be set. SFLAG sets event flag 65(19@), which unblocks WFLAG. 
Run WFLAG first, then run SFLAG. 


The following notes are keyed to the examples. Note 5 is in 
SFLAG; all others are in WFLAG. 


@ Create the group global event flags. The default group 
number (used here) is the group number that the task is 
running under. 


An error is reported if the flags already exist. This 
isn't a fatal error, so we check for this condition. If 
the flags do exist, print a message and continue. 


The flag is in an unknown state at startup. Therefore, we 
must clear the flag before waiting for it to be set. 


Wait for the event flag to be set by SFLAG. This causes 
WFLAG to be blocked. Now run SFLAG. 


Set event flag 65 in task SFLAG. This allows WFLAG to 
become unblocked. SFLAG then exits. 


When WFLAG is unblocked and it continues executing, it 
starts up here. We check for any directive error entering 
the Wait For state, print a message, and exit. 


In certain programming Situations it may be necessary to test one 
or more event flags to see if they are currently clear or set. 
The CALL READEF directive can be used to read ae single flag. 
After the flag has been read, the contents of the DSW will 
determine the condition of the flag. If DSW=2, the flag was’ set; 
if DSW=8, the flag was clear. 
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PROGRAM WFLAG 
C FILE WFLAG.FTN 


Ct This task creates the srour slohbal event flags» and 


~ then clears event flas 65. and waits for it to be set. 
( When the flags is sety it writes 3s messasde and exits 


oe 


C Install end run instructions? 


C 

C Rum WFLAGy then rum SFLAG. At least one of the 

fe tasks must be installeds or else the RUN command 
C Will try to install hoth tasks under the same 

3 name CTTnrd 

af: 


WRITE (S10) 
10 FORMAT (’ WFELAG IS CREATING THE GROUF GLOBAL EVENT 
1 FLAGS’) 
CALL CRGF (»InSW) 
IF (IDNSW LT. 0) GOTO 900 
15 WRITE (5»20) 
20 FORMAT (’ CLEAR ANID THEN WAIT FOR EF 65. TO BE SET’) 
CALL CLREF (65> I0SW) 
IF (1NSW LT. 0) GOTO 1100 
4] CALL WAITFR (465»I0SW) 
IF (IUSW .LT. 0) GOTO 1200 
re) WRITE (3930) 
30 FORMAT (’ EF 65. HAS BEEN SET. WFLAG WILL NOW EXIT‘) 


CALL EXIT 

C Error rrocessing 

C: 

C Check for code of ~17» meanings flass already exist 

900 IF (I0SW .NE. ~-17) GOTO 1000 ; 

C In that casey Just dislay a message and continue. 

6 WRITE (S910) 

910 FORMAT ¢’° GROUP GLOBAL EVENT FLAGS ALREADY EXIST’) 

GOTO 15 


C Here for fatal errorss disrelsy message and exit 
1000 WRITE (Ssi1010) InSwW 


1010 FORMAT (”% DIRECTIVE ERROR CREATING GROUP GLORAL 
IEF ’’S. DSW = “9TS) 
CALL EXIT 

1100 WRITE (S»1110) TOS 

LLLO FORMAT ¢(% DIRECTIVE ERROR CLEARING EVENT FLAG 65. 
1 USW = ’»IS) 
CALL EXIT 


Example 2-3 Waiting for an Event Flag (Sheet 1 of 2) 
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1200 WRITE (591210) InswW 

1210 FORMAT (’ JIIRECTIVE ERROR WAITING FOR EVENT FLAG 
1 65. DSW = ’sIS) 
CALL EXIT 
ENT 


Run Session 


“INS WFLAG 
>INS SFLAG 
“RUN WFLAG 


“UFLAG IS CREATING THE GROUF GLOBAL EVENT FLAGS 
CLEAR AND THEN WAIT FOR EF 65. TO BE SET 
RUN SFLAG 


EF 65+ IS BEING SET. THEN SFLAG WILL EXIT. 
EF 65. HAS BEEN SET. WFLAG WILL NOW EXIT 


Example 2-3 Waiting for an Event Flag (Sheet 2 of 
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FROGRAM SFLAG 
( FILE SFLAG.FTN 


C This task sets event flags 65. It assumes that the 
(2 srour global event flags have already been created. 


C Install and run instructions? 


“CG Rum WFLAGs then rum SFLAG. At least one of the 

C tasks must be installed» or else the RUN command 
C will try to install both tasks under the same 

C mame CTTrimd. 

C; 


WRITE (5210) 
FORMAT ¢(¢ EF 65. IS BEING SET. THEN SFLAG WILL EXIT’) 
@ cae Serer ¢65,rnsw) | 
( The USW value returned for SETEF is 2 if it was set 
Cf and GO if it was cleser. Al is NOT returned for success 
IF (iInSW .LT. 0) GOTO 1000 
CALL EXIT 
( Error cade 
10900 WRITE (391010) 
1910 FORMAT ¢€’% DIRECTIVE ERROR SETTING EF 65. SW = 7” 
Ly T4) 
CALL EXIT 
ENT 


Example 2-4 Setting an Event Flag 
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ASYNCHRONOUS SYSTEM TRAPS (ASTs) 


Asynchronous System Traps (ASTs) are used to detect events”) that 
occur asynchronously to a task's execution. We say that they 
occur asynchronously to a task's execution because they occur at 
unpredictable times, depending on conditions which the task cannot 
control. By doing some work and then periodically checking an 
event flag to check on an event, a task can do work while waiting 
for an event to occur. However, this means that the task must 
periodically stop its work to check the flag. 


Using an AST gives the Executive the responsibility for monitoring 
the event. The Executive will "interrupt" the task and transfer 
control to a special user written routine when the event has 
occurred. Using this technique is more efficient because the task 
doesn't have to do any periodic checking, and it probably results 
in faster notification because the task is notified right after 
the event occurs. With periodically reading the flag, it may take 
quite a while to notice that the event has occurred if it occurs 
immediately after a check. —- 


The only directives which allow the use of ASTs from FORTRAN are 
CNCT, PWRUP, SDRC, SDRP, SPAWN, SREA and SREX. 
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2-1 shows how an AST routine works. The following notes 


are keyed to the figure. 


For 


The user specifies an AST routine in a. directive. The 
Executive sets up for the AST. 


The Executive returns control to the user task. 


When the system determines that the event has _ occurred 
which corresponds to the specified AST routine, the 
Executive passes control to the AST routine, executing it 
before any other user code in the task. This means that if 
the task is executing at the time of the AST, the task is 
"interrupted" until the AST routine is executed. The AST 
routine is executed even if the task is stopped or blocked. 
In that case, the task returns to its stopped or blocked 
State after the AST routine is executed, unless the AST 
routine or some external event unstops or unblocks the task 
in the meantime. 


The AST routine is a user written routine contained within 
the task. 


The AST routine uses a Standard RETURN statement to return 
control to the main code via the Executive. However, 
before the actual return, the Executive checks to see if 
any other ASTs have occurred while the AST routine was 
executing. Any such additional ASTs are queued in an AST 
pending queue in a first-in-first-out order; these ASTs 
are also serviced before the Executive returns to the point 
at which the AST interrupt occurred. 


additional information on ASTs, see section 1.5.4 in 


Chapter 1 and sections 2.3.3 and 2.3.4 in Chapter 2 of the 
RSX-11M/M-PLUS Executive Reference Manual. 
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TASK CODE EXECUTIVE CODE 


EXECUTIVE DIRECTIVE 
SPECIFYING AST 


MAIN | | ROUTINE 


AST 
SERVICE 
CODE 


ASTX$S 


TK-7508 


Figure 2-1 AST Sequence 
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Example 2-5 shows the use of ASTs. An AST routine is entered if 
an abort request is made by either another task or an operator. 


The following notes are keyed to the example. 
@ Set up for AST on abort attempt. 
@ loop until abort request comes in. 


@ Service routine entered on first abort request. For this 
particular AST, a nonprivileged task enters this routine 
only once and further ASTs are cancelled. If the task is 
built as a privileged task, the routine is entered each 
time an abort attempt comes in. See Appendix D for an 
explanation of privileged tasks. 3 


| 4 Note that FORTRAN I/O cannot be performed in an AST routine 
because the I/O code is not reentrant; therefore any I/O 
to be done in an AST routine must be done via _ QIO 
directives. The next module will discuss the QIO directive 
in detail. 


Another directive, SREX, gives extended capabilities. An entry 
passed to the AST routine indicates whether the abort request came 
from a privileged or nonprivileged task or user and further, 
whether it came from an Abort Task directive or a DCL (or MCR) 
command. Each case can be handled differently. 
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FROGRAM ASTEX 
C FILE ASTEX.FTN 


C This task sets ur @ Srecify Reauest Exit AST routine. 
~ It then sits in @ looe until someone tries to abort 

” ite AL that rointes it enters the AST routine and sends 
~ OWL & messade. It won’t abort the first time. A second 
. short attemet will succeed hecause for this rarticuler 
~ AST» the first AST entry cancels any further AST’s for 
> this event 


C Comeile instructions? 

C Tne AST routine must he comeiled with traceback. 

~ Gisadbled. Since in this case the AST routine source 

C is in the same file as the mainlines comrile both with 
® traceback disabled. 

CG For FORTRAN IV3 

C FORTRAN/NOLINE..NUMBERS/LIST ASTEX 

@ For FORTRAN TV-FLUS or FORTRAN-77 

C FORTRANEC/F4F or /SF77I/NOTRACE/LIST ASTEX 


C Run motes? Remember to use the name the task is 
© installed under when attempting to short the task. 


C~ 
INTEGER DSW 
EXTERNAL REXAST 
CALL SREACREXAST » NSW) ! Set our Srecify Exit AST 
IF (MSW.LT.O> GOTO 1001 ! Branch on error 
TYFE Xe ’ASTEX STARTING UF. WILL WORK UNTIL ABORTED. 
Yo some work. 
10 NO 20 P= ~32767 932767 
Oleo CONTINUE 


GO TQ 10 
CO Error cade 


1001. TYFE X»’ERROR ON DITRECTIVEs DSW = “yy tSwW 
CALL EXIT 
ENYI 


Example 2-5 Using a Requested Exit AST (Sheet 1 of 2) 
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C | 
© SuBROUTINE REXAST 

C 

C AST service routine 

G 


INTEGER FLISTC3)»IOWVE 
REAL TEXTIC6) 9 TEXT2¢07) 
DATA ITOWVB/*11000/7 
ATA TEXTL /’TRYI’s’NG T’9’O ABs 
L’ORT “’»’ME “’s’EHP 77 
QATA TEXT2 /°WE Wes ’ON’4T% os? LET’ » 
1’ YOU’ s’ THI’s’S TI’s’ME! “7 

( Set-ur for QIO directive 
CALL GETADRCFPLIST CL »sTEXTIC1)> 
PLIST(2) = 23 
FLISTCS) = *4O 

Use Q10 directive to disrelay tex 
CALL WTQATOCTOWVB:ySelyyyPLIST> 

CO Setour for 2nd line of text 
CALL GETADIRCFLISTCLI »sTEXT2¢1)) 
FPLIST(2)9 = 27 

(CC Use QIO directive to disrlay text 
CALL WTQTOCTOWVBsSetvsePLIST) 
RETURN 
ENT! 


Run Session 


»INS ASTEX 

*RUN ASTEX 

ASTEX STARTING UF. WILL WORK UNTIL ABORTED. 
ABORT/TASK ASTEX 


TRYING TO ABORT MEs EH? 
WE WON’T LET YOU THIS TIME! 
ABORT/TASK ASTEX 
10357202 Task "ASTEX * terminated 
Aborted via directive or CLI 


"% 
= 


Example 2-5 Using a Requested Exit AST (Sheet 2 of 2) 
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Now do the tests/exercises for this module in the tests/exercises 
book. They are all lab problems. Check your answers against the 
solutions provided, either in that book or in on-line files, under 
UFD [202,2]. 


You will need the program READF.FTN to do question 1. It should be 
available on-line probably under UFD [2@2,1]. In case it is not 
available on-line, the source code is listed in Appendix G. 


If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, return to 
this module for further study. 
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USING THE QIO DIRECTIVE 


INTRODUCTION 


All Input/Output under RSX-11M is performed using QIO directives. 


In this 


module, you will learn how to use the QIO directive, 


concentrating on its use for input/output to a terminal. 


OBJECTIVES 


To use the QIO directive to perform I/O to a 
non-file-structured device 


To choose either synchronous or asynchronous I/0 as_ the 


most effective method 


To perform complete error checking upon I/O completion 


RESOURCES 


RSX-11M/M-PLUS Executive Reference Manual, Chapter 5 for 
specific directives 


RSX-11M/M-PLUS I/O Driver's Reference Manual, Chapters 1 


and 2 
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OVERVIEW OF QIO DIRECTIVES 


All I/O operations under RSX-11M are performed — using QIO 
directives. While transparent to the user, all FORTRAN READ and 
WRITE statements are ultimately transformed into QIO directives. 
The QIO directive causes an I/O request to be passed to the 
appropriate service routine. The service routine is either a 
device driver or a system task called an ancillary control 
processor (ACP). There is a device driver for each device type on 
the system. There are three ACP's provided, FI1ACP for FILES-11l 
structured disks, MTAACP for ANSII magtape, and NETACP for DECNET. 


The I/O packet is placed in an I/O queue for the service’ routine. 
The packets are queued in the order of the priority of the issuing 
tasks. If there are multiple requests at a given priority, those 
requests are queued first-in-first-out (FIFO). The QIO directive 
does not perform the I/0 operation itself, but simply queues’ the 
request to the appropriate service routine, which performs the 
actual I/O transfer. After the I/O request has been queued, the 
Executive returns control to the issuing task, unless the task 
requests the Executive to place the task in a Wait For state until 
the I/O transfer completes. 


PERFORMING I/O 


QIO directives are generally used by a programmer for I/O on 
non-file-structured devices such as terminals. For file I/O, all 
READ and WRITE statments are passed off to the File Control 
Services (FCS) or Record Management Services (RMS), which in turn 
issue the appropriate QIOs for you. When using QIOs, you’ specify 
which I/O operation (e.g., Read Virtual Block or Write Virtual 
Block) is to be performed by means of an I/O function code. 
Specify the device by means of the logical unit number (LUN). You 
specify additional information about the I/O operation (e.g., what 
buffer to write and how many characters) by means of an I/O 
parameter list (IOPL). All of this information is passed to the 
Executive through parameters in the Directive Parameter Block 
(DPB), as it is with all directives. 
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USING QIO DIRECTIVES IN FORTRAN 
There are two basic reasons for using QIO directives in FORTRAN. 


@ To acheive asynchronous I/0. 


All READ and WRITE statements are synchronous; i.e., the 
program is put into a Wait For state until the I/O is 
complete. If you need to perform asynchronous I/O, it can 
only be done via. QIO directives. 


e To perform I/O functions not possible with READ and WRITE 
statements. 


Certain I/O functions, particularly to a terminal, cannot 
be done by READ and WRITE statements. Some examples are 
read with no echo and cursor control on a video terminal. 
By uSing QIO directives, these functions can be done from 
FORTRAN programs. 


1/0 FUNCTIONS 


Each device type has its own set of legal I/0 functions. Certain 
functions are called standard or common, since they are available 
on all devices. The seven standard I/O functions are listed in 
Table 3-1. Logical block transfers (Read Logical Block and Write 
Logical Block) can usually be performed for any device. For file 
Structured devices, virtual block transfers can be performed only 
if a file is open on the device. 


If Virtual Block I/0 is requested for a non-file-structured 
device, such as a terminal, it is converted to logical block I/O 
for you. In addition, devices may have additional device specific 
-functions, such as Read No’ Echo at a terminal. Each function 
requires its own set of parameters, which are specified in an I/O 
parameter list. 


66 


USING THE QIO DIRECTIVE 


Table 3-1 Common (Standard) I/0 Functions 


Global Symbol Octal | Suggested 
in MACRO Value Function — FORTRAN Name 
IO.ATT OG140@B Attach device IOATT 
I0.DET GH2G0B Detach device IODET 
IO. KIL @GGG12 Cancel I/O requests IOKIL 
IO.RLB GB198B Read Logical Block IORLB 
10.RVB 910490 Read Virtual Block  IORVB 
IO0.WLB GOG490 Write Logical Block IOWLB 
IO.WVB 11990 Write Virtual Block IOWVB 


Throughout the literature you will find I/O function codes given 
in the form used by MACRO programmers; for example, IO.ATT and 
IO.DET. In MACRO, these codes can be used directly as function 
codes in a QIO directive, and the proper octal values will be 
inserted. In FORTRAN, you must determine the octal value for’ the 
function and use that value in the CALL QIO or CALL WTQIO. For 
instance, to issue an ATTACH, you could use: 


CALL QTO("140G,e5 47007) 


In order to make QIO calls more readable, it is recommended that 
you create a DATA statement for any needed QIO functions using the 
suggested variable names shown above. While the actual name is 
arbitrary, (but must be an integer variable), a certain degree of 
standardization will be achieved by using the MACRO symbol without 
the period (IOATT versus IO.ATT). Hence to perform an ATTACH: 


DATA IOATT/"1400/ 
CALL QIO(IOATT, sy, 7777) 


The octal values for all function codes can be found in Appendix B 
of the RSX-11M/M-PLUS I/O Driver's Reference Manual. 
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LOGICAL UNIT NUMBERS (LUNs) 


The device for an I/O operation is specified by means of a logical 
unit number. The correspondence between logical unit numbers and 
physical devices is made initially at task- build time. 


The default LUN assignments set up by the Task Builder are as 
follows: 


LUN #1 —- SY: 
LUN #2 - SY: 
LUN #3 - SY: 
LUN #4 - SY: 
LUN #5 - TI: 
LUN #6 - CL: 
LUN #7 - TI: 


LUN 7 is typically used for error messages. 


These default assignments may be overridden at task-build time by 
using the ASG _ option. Additional LUNs can be created (up to a 
total of 25@ LUNS) by using the UNITS option. 


Once a task is installed, an operator can check’ the LUN 
assignments for the task by using the DCL SHOW LOGICAL UNITS 
command (LUN in MCR). The assignments can be changed by an 
operator using the DCL ASSIGN/TASK command (REA in MCR). The LUN 
assignments can also be checked at run time using the Get LUN 
directive (CALL GETLUN), and changed using the Assign LUN 
directive (CALL ASNLUN). 


SYNCHRONOUS AND ASYNCHRONOUS 1/0 


There are two kinds of I/0, synchronous I/O and asynchronous’ I/O. 
With synchronous I/0, the Executive provides sychronization. When 
a task issues an I/O request, it doesn't get control back from the 
Executive until after the I/0 packet is queued, and the I/0 
operation (the transfer performed by the service routine itself) 
is completed. In other words, the synchronous I/O request asks 
the Executive to queue the I/O packet and then place the task in a 
“Wait For" state, waiting for the specified event flag to be set, 
at which time the actual I/O is complete. | 
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Figure 3-1 shows the flow of instructions during the processing of 
a synchronous I/O operation. The task does not execute the 
instruction following the QIO directive until after the I/0 
transfer itself has completed. 

Figure 3-2 shows a time diagram illustrating the same I/0 
operation. Note that once the QIO directive is executed at step 
1, the task doesn't execute again until step 8, after the transfer 
has completed. The system handles all synchronization with 
synchronous I/O. Use the CALL WTQIO directive to invoke this type 
of I/O. (CALL WTQIO is a combination of a QIO and a WAITFR). 


Commentary to Figures 3-1 and 3-2: 

User task executes WTQIO directive. 

Executive queues the I/0 request. 

Executive calls the driver. 

Driver begins the I/O transfer. 

Driver handles I/O transfer as necessary. 

I/O transfer completes. 

Driver finishes up and notifies task the I/O is completed. 


User task continues. 
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EXECUTIVE 


QIO DIRECTIVE 
ROUTINE 


USER TASK 


@oio pirective 


DEVICE DRIVER 


1/0 QUEUE 


TK-7507 


Figure 3-1 Execution of a Synchronous I/O Request 


USER TASK 


i 
QIO DIRECTIVE 


DRIVER 


1/0 TRANSFER 


TIME 


TK-7 509 
Figure 3-2 Events in Synchronous I/0 
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With asynchronous I/0, the Executive still queues the I/O request. 
However, when a task issues an asynchronous I/O request, the 
Executive passes control back to the task immediately after the 
I/O packet is queued to the driver. You must provide 
Synchronization concerning the completion of the actual 1I/0 
transfer. This could occur at various times, depending upon such 
factors as how many other I/O packets are already in the driver's 
I/O queue, and the speed of the device itself. The task executes 
in parallel while the I/O transfer takes place. In Figure 3-3, 
the instruction after the QIO request is executed after the I/0 
packet is queued and the driver has. started the transfer, not 
after the I/O transfer completes. The task continues executing 
unless it chooses to wait. Figure 3-4 shows a time diagram 
illustrating asynchronous I/O. 


Note that after the QIO directive is executed at 1, the task 
begins executing again at step 5. In this example, the task 
waits for the I/O transfer to complete at step 5a. If you use 
asynchronous I/0, you must provide any synchronization yourself, 
uSing event flags or by testing the I/O status’ block. The’ task 
shown in Figures 3-3 and 3-4 uses a Wait For Event Flag directive 
at step 5a. Use the directive CALL QIO to invoke this type of 
I/O. 


The advantage of asynchronous I/O is that your task can continue 
processing in parallel with the I/O transfer. For example, you 
can perform computations while waiting for a read or a write 
operation to complete. Of course, if you need the information 
from the read before you can do anything else, it is better to use 
synchronous I/0. 
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Commentary to Figures 3-3 and 3-4: 


User task executes QIO directive. 
Executive queues I/O request. 


Executive calls the driver. 


Driver begins the I/O transfer, and passes control back to 


the user task. 


Driver handles I/O transfer as necessary. 
executes in parallel with I/O transfer. 


User task waits for I/O operation to complete. 
I/O transfer completes. 


Driver finishes up and Executive notifies task 
completed. 


User task continues. 


72 


User task 


that I/O is 


USING THE QIO DIRECTIVE 


EXECUTIVE 


QIO DIRECTIVE 
ROUTINE 


USER TASK 


1/0 PACKET 


1/0 QUEUE 


TK-7518 


Figure 3-3 Execution of an Asynchronous I/0 Request 
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QiO DIRECTIVE 


DRIVER 


1/0 TRANSFER 
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Figure 3-4 Events in Asynchronous I/0 
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MAKING THE I/O REQUEST 


Specify the following information in the CALL QIO or CALL WTQIO 
when requesting I/O: 


e Synchronous or asynchronous I/0, by using the appropriate 
directive. 


e The I/O function to be performed. 
e The LUN to be used for the I/0 operation. 


e An event flag number, if any, to be used for 
synchronization. This is required for synchronous I/O. 


e The address of an I/O Status Block (IOSB). The IOSB is 
used to pass status and other information about the I/0 
operation back to the task. ; 


e The I/O parameter list (up to six words) which specifies 
information for the particular device and I/O function 
requested. 


e The Directive Status Word (DSW) 


Table 3-2 shows the I/O parameter list arguments which are _. needed 
for each of the standard I/O functions with the full-duplex 
terminal driver. Note that for write logical block and write 
virtual block, the vertical format control characters are the 
standard FORTRAN carriage control characters. 


Table 2-3 in section 2.3 of the RSX=11M/M-PLUS I/O Driver's 
Reference Manual lists these standard functions and the other 
device-specific functions available with the full-duplex terminal 
driver. The device-specific functions will be discussed later in 
this module. If your RSX-11M system has the half-duplex terminal 
driver, Table 3-3 in section 3.3 lists the functions available 
with that driver. For other devices, there is a corresponding 
table in the appropriate chapter of the manual. 
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Table 3-2 I/O Parameter List for Standard I/O Functions 


Function I/O Parameter List 
Attach None needed 
Detach None needed 
Kill None needed 


Read Virtual Block word 1 - buffer starting address 
and word 2 - buffer size (in bytes) 
Read Logical Block word 3 - optional timeout count 
(in 18 second intervals) 
NOTE: Only used if a special sub- 
function bit is set. See the 
section on Terminal I/0. 
words 4, 5, and 6 - unused 


Write Virtual Block word 1 - buffer starting address 
and word 2 - buffer size (in bytes) 
Write Logical Block word 3 - vertical format control, as 
follows (these are the standard 
FORTRAN carriage control char- 
acters): 


Octal ASCII 
value character Meaning 


G4B blank © single space 

G6B 4) _ double space 

G61 J form feed 

G44 $ prompting output- 


stay in same 
location after 


output 
G53 + overprint 
ry) null no implied format 


control - use 
internal control 


words 4, 5, and 6 - unused 
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THE 1/O PARAMETER LIST IN FORTRAN 


The parameter list must refer to an integer array declared in a 
DIMENSION statement with a dimension of six. When used in a QIO 
directive, the parameter list array name is used without a 
subscript. 


DIMENSION IPAR(6) 
CALL QI0O(,,,,,I1PAR,) 


Some entries in the parameter list must be the addresses of arrays 
or variables. Since FORTRAN does not provide this capability, you 
must use a system subroutine called GETADR to get the addresses. 
(See the RSX-11M/M PLUS Executive Reference Manual and the 

appropriate user's guide for further information. To get’ the 
addresses of two variables IBUFF and JBUFF and place the addresses 
in array K, use the following: 


DIMENSION K(2) 
CALL GETADR(K,IBUFF,JBUFF) 


The address of IBUFF will be in K(1l) and the address of JBUFF will 
be in K(2) at the completion of the CALL GETADR. 


ERROR CHECKING AND THE I/O STATUS BLOCK 


There are two kinds of errors which can be produced by QIO 
directives, directive errors and I/O errors. The various 
directive and I/O status codes and their meanings are listed in 
Appendix B of the RSX-11M/M-PLUS I/O Drivers Reference Manual and 
also in the RSX-11M Mini-Reference. 


Directive errors are produced due to errors in processing’ the 
directive and getting the I/0 packet queued up to the device 
driver. As with other directives, QIO directive errors are 
indicated by a negative value in the DSW upon return to the task 
code. Success is indicated by a positive value (typically +1) in 
the DSW. Thus, the directive status indicates the success or 
failure of the attempt to queue the I/O packet. Check for 
directive errors immediately upon return to the task, after the 
QIO directive is issued. 
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Upon completion of the I/O transfer itself, the Executive returns 
status information concerning the I/O transfer to the I/O Status 
Block laid out as. follows: 


Device Dependent I/O Status word 
Actual Number of Bytes Transferred word 


The low-order byte of the first word of the I/0 Status Block 
contains the I/O status code. Note that this is a byte value, not 
a word value. A positive I/O status code (usually +1) indicates 
success. Negative values indicate various error conditions. The 
second word of the I/O status block indicates the number of bytes 
actually transferred, which is significant in the case of any read 
or of a write which ends after only some of the data is 
transferred. The device dependent byte indicates, for reads, the 
character which was used as a terminating character (<RET>, 
CTRL/Z, <ESC>, etc.). 


The I/O status byte should be checked only after the I/O transfer 
completes. For synchronous I/0, the I/O status should be checked 
immediately after checking the DSW, since the I/O transfer itself 
also completes before control is returned to you. For 
asynchronous I/0, on the other hand, the I/O status should be 
checked when the task is notified by the Executive that the 
transfer is complete. Synchronization is discussed in the 
following section, after an example of synchronous I/O. 


THE QIO DIRECTIVES 
Synchronous 1/0 
The format of the CALL WTQIO is: 


CALL WTQIO(ifn,lun,efn,pri,iosb,iopl,ids) 


where 

ifn - I/O function code 

lun - Logical unit number 

efn - Event flag number (required for synchronous I/0) 

pri - Priority (not used but must be present) 

iosb - I/O status block address 

iopl - I/O parameter list, integer array up to six elements 
ids - Directive status word 
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An event flag must be specified for synchronous I/O. If one is 
not specified, the I/O request is handled as an asynchronous I/0 
request. The priority is included to allow compatibility with 
RSX-11D.. It is not used in RSX-11M. The I/O parameter list is a 
Single directive parameter. Hence, the entry must be for an array 
of up to six elements. Six words are always placed in the DPB for 
the I/O parameter list, whether or not all six words are 
specified. It is best to reserve six words. If you do not, you 
may end up with data from the array(s) defined immediately after 
the variable defined for the parameter being used in the parameter 
list for a QIO. 


Example 3-1 shows the use of synchronous QIOs. The following 
notes are keyed to the example. 


od The two-word (four-byte) I/O status block for return of 
I/O status and the buffer into which the data will be read 
and from which the data will be displayed. IOSB is 
declared as a byte array so that the program can examine 
the I/O status byte in IOSB(1). The program also needs to. 
use the byte count of the number of bytes read by the QIO. 
This count is found in IOSB(3) and IOSB(4). Since the 
program needs this as an integer value, the 
EQUIVALENCE (NUM, IOSB(3)) is used. 


IBUF is the buffer used to hold the characters read by the 
WTQIO directive. 


2 Issue the read request. We are using LUN 5, event flag l, 
and IOSB which is the four-byte (two-word) array to 
receive I/O status after the IORVB. The I/O parameter 
list is set up as a single parameter (IPAR) which refers 
to an integer array. IPAR(1) must contain the address of 
IBUFF which is the buffer into which the characters will 
be read by the IORVB. Since this is an address, use CALL 
GETADR to get the address into IPAR(1). IPAR(2) is the 
maximum buffer size for the IORVB. If input is terminated 
with a terminating character, such as a carriage return, 
before 8% characters are typed, the number of characters 
actually read will be returned in the second word of the 

status block (IOSB(3)). Input will be terminated 
automatically after the eightieth character, if 8@ 
characters are typed. In that case, 8@ will be returned 
in the second word of the status block. 


@ Check for directive error - failure to queue the I/0 
packet. ; 


78 


USING THE QIO DIRECTIVE 


With synchronous I/0, the I/O operation has completed when 
we get control, so also check the I/O status. A value 
less than @ indicates an error in the I/O transfer. 


The count of characters typed in is in NUM (IOSB(3)). 
Check on and convert only this many characters. Check 
each character to see if it is in the range ASCII A _ to 
ASCII Ze If so, convert to lowercase by adding 
32(10)=48(8) to that value, or else continue. 


Write the buffer BUFF, which has the converted message. 
This is a Write Virtual Block. The third argument in the 
I/O parameter list, "49, is for vertical format control. 
"48, which is an ASCII space, indicates single line feed 
before writing the line. 


Check for directive error or I/O error. 


NOTE 

Although both virtual block and logical block 
operations are permitted to a terminal, it is 
safer to use virtual block operations. If 
the I/0 is actually performed at a terminal, 
the virtual block request gets converted to a 
logical block request. If logical block 
writes are used and someone reassigns the LUN 
to a disk, for example, the write may 
overwrite a block on the disk. If, on the 
other hand, someone reassigns the LUN and 
write virtual blocks are used to a disk, the 
write will only be allowed if a file is open 
on the disk, which will fail in most cases if 
the program is writing to a terminal. 
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FROGRAM SYNCHQ 
Co FILE SYNCHQ.FTN 
> converts ary urrer case cheracters to lower case and 


> Prints the converted message back at the terminal. 
GO It uses sunehronous QIO directives. 


{ 

t 

{ : ? 

CO This rrogram reads a line of text from the terminal » 
Cc 

{ 


BYTE TOSBC(4)»TRUF C80) 
QNIMENSTION ITFPARCS6) 
EQUIVALENCE (CNUM»s TOSB¢(3))> 
DATA TOWVB/ "110007 
MATA TORVEZA*10400/ 
NATTA IVFC/"*40/7 
{? Seto our values for the QI0 
TUNE T=3 
IF AR C2) =80 
TFAR CS =IVEC 
(] Get the address of the I[/0 buffer 
CALL GETADRCTIFARCL >) »TBUF C1) 
C Issue the QL0 
— CALL WTQTOCTORVEs TUNTT ol» »TOSByITFAR»s ItS> 
( Check the directive and I/0 statuses 
IF (10S .LT. 03 GO TO 800 
Orr CITOSBC(1) LT. 0) GO TO 810 
C Check for urrercase characters and convert them to lowercase 
no 100 I=1»NUM 
IF CIBUF CTI) oT. *A%) GO TO 100 
6 IF CIBUF CI) .GT. 90) GO TO 100 1Z is 9O(10) 
TRBUF CLT )=ILBUF CT D+4+32 
1O0 CONTINUE 
0 Flace the number of characters to write in the I/0 rsrameter list 
IF AR(C2)=NUM 
C Write the cornverted line to the terminal 
CALL WTQTOCTOWVB»sTIUNTI Ted» sITOSBsTPAR» Tins) 
C Check directive and I/O status 
IF €I0S oT. 0) GO TO 820 
IF (TOSBC1)> LT. 0) GO TO 830 
GQ TO 850 
B00 WRITE CS» 900) TNS 
30 TO 8So 
B10 WRITE CS s 910) TOSBC1) 
60 TO 8S 
B20 WRITE CS» 9209 T0S 
GO TQ 850 


Example 3-1 Synchronous I/O (Sheet 1 of 2) 
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330 WRITE CS» 930) TOSBC 1) 
8BSO CALL EXIT 
POO FORMAT(’ DIRECTIVE ERROR ON READy CODE = “»T4) 
910 FORMAT(’ I/70 ERROR ON REATt»y CODE = ’»T4) 
920 FORMAT(C’ DLTRECTIVE ERROR ON WRITE» CONE = ’»T4) 
930 FORMAT(’ I/0 ERROR ON WRITE» CODE = ’»f4) 

ENT 


Rum Session 


>RUN SYNCHQ 
ABCIEFGHI Jk lmnorarstuvwxy21 23456780 IN 
gbedefahidkilmnorarstuvwxs212345678C 1\ 


Example 3-1 Synchronous I/O (Sheet 2 of 2) 


81 


USING THE QIO DIRECTIVE 


Asynchronous I/O 
The format of the CALL QIO is: 


CALL QI0O(ifn,lun,efn,pri,iosb,iopl,idsw) 


where 

ifn - I/O Function code 

lun - Logical Unit Number 

efn - Event Flag Number 

pri - Priority (not used but must be present) 


iosb - I/O Status Block Address 


iopl - I/O Parameter List (up to 6 words) 
idsw - Directive status word 
Synchronization With Asynchronous I/O -- As mentioned earlier, 


event flags may be used for synchronization. If an event flag is 
specified, the Executive clears the event flag when the I/O packet 
is queued and sets the flag again when the I/O transfer completes. 
This happens with both synchronous and asynchronous I/0, if an 
event flag is specified. With asynchronous I/O, the task can 


specify a flag and use it for synchronization using one of the 
following techniques: 


1. Do some work, then wait for the flag to be set. 


2. Work the entire time, periodically checking the flag until 
it is set. 


A third technique is to monitor the contents of the I/O status 
byte of the I/0 status block. The entire I/O status block is 
cleared when the I/O request is queued to the driver. Later, it 
is filled in when the I/O transfer completes. Therefore, the user 


task can periodically check the contents of the I/O status byte 
for a nonzero value. 
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Example 3-2 demonstrates the use of asynchronous I/0 to. perform 
the same function performed in Example 3-1. This task can do some 
work in parallel with the I/O transfer. The following notes are 
keyed to the example. / 


1) Issue the read via CALL QIO instead of CALL wWTQIO. All 
arguments are the same as for a CALL QIO. The Executive 
will clear event flag 1 when the I/O packet is queued and 
set it when the I/O operation completes. 


@ check for directive errors immediately. Here, we are 
checking for an error in queueing the I/O packet. 


While the I/O transfer itself takes place, we can do some 
work. Here we fill the array at K with the values 64, 
128, 022,048. 


When we are finished with our work, we wait for the event 
flag specified in the CALL QIO directive. It will be set 
when the I/O operation completes. 


Now that the I/O operation is finished, check for I/O 
errors. 


After converting the message to lowercase, issue the 
write. 


This time, we wait for the flag to be set right after we 
check the directive status. We could do some more work 
here. If in fact we are going to just wait, it is simpler 
and more efficient to use synchronous I/0 (WTQIO). 
Synchronous I/O is more efficient because we perform both. 
functions (QIO and WAIT) in one Executive directive call. 


If you use an asynchronous QIO for either reading or writing, you 


should not use a FORTRAN READ or WRITE to the same lun until you 
are certain that the QIO has completed. 
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FROGRAM ASYNCR 
C FILE ASYNCQ.FTN 


- This ferosram reads a line of text from the terminal» 
2 Canverts any urrer case characters to lower case and 
. Prints the converted messase hack at the terminal. 

> It uses asenmchronous QTO0s and an event flags for 

C synchronization. 


BYTE TOSBC4) »T BUF (80) 
QIMENSTION ITFARC6) 9K 010) 
EQUIVALENCE (CNUMs TOSBC3) > 
DATA TOWVB/* 11000/ 

DATA TORVE/S "104007 


{ Geb ur values for the QI0 
IUNTT#5 
TPAR C2)=80 
TPAR CS) =LVFC 
( Get the address of the I/0 buffer 
CALL GETAIIRCIPARCL) » I BUF C1)) 
We the QI0 
CALL QTOCTORVEy TUNITsSy*TOSBsITPARs TINS > 
Check the directive status 
2) IF (ims .LT. 0) GO TO 800 
( Do some work while I/0 oreration is heingd rerformed 
@ no SO T=1%10 


~ 
ed 
isi 
wi 
c 
% 


ROTI =464xT 
30 CONTINUE 
tC Wait for £/0 to comelete 
6 CALL WAITFR(SsI0S) 
Cheek directive status 


IF (InS ..LT. 0) GO TO 805 
® Check the [70 status 
IF (CIOSBC1) .LT. 06) GO TO 810 
CG Convert to lowercase 
rg) 100 IT=1»NUM 
IF ¢2TBUF CTD LT. “A’) GO TO 100 
IF (IBUF CTI) .GT. °132) GO TO 100 
TBUF CI) =IBUFCIO432 
100 CONTINUE 
) Setoue I/0 Farameter List for write 
ITP AR C22=NUM 
.@ the canverted line to the terminal 
CALL QTOCTOWVEs IUNTTsS»+TOSKRy ITFPAR»s IS) 
C Check directive status 
IF (10S .LT. 0} GO TO 820 


or 


C. Wri: 


Example 3-2 Asynchronous I/O Using Event Flags 
for Synchronization (Sheet 1 of 2) 
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CG Wait 
i Check 


C Check 


USING THE QIO DIRECTIVE 


for the I/0 to comerlete 


CALL WAITER (Ss Ins) 

directive status 

IF (ins .LT. 0) GO TO 8238 

the I/0 status 

IF (TOSBC(1) LT. 09 GO TO 830 
GO TO 850 

WRITE CS 2900) 10S 

GO TO 850 

WRITE CS» 90S) 20S 

GQ TO 830 


GO TO 850 

WRITE CSs 920) 00S 

GO TO 850 

WRITE CSs925) 10S 

GO TO 88o 

WRITE CS 9930) TOSBC1) 

CALL EXIT 

FORMAT (C’ DTRECTIVE ERROR ON READty CONE = “»T4) 
FORMAT(’ DLTRECTIVE ERROR ON IST WAIT,» CODE = ’sI4) 
FORMAT(C’ I/70 ERROR ON READty CONE = %»T4) 

FORMAT(C’ DTRECTIVE ERROR ON WRITEs CODE = ‘’+T4)> 
FORMATC’ DIRECTIVE ERROR ON 2NI WAIT» CODE = “’914) 
FORMATC’ IT/0 ERROR ON WRITEs COME = ’914) 

END 


Run Session 


=7RUN ASYNCQ 
abode fshkK JHKJHKHFRTEWawryugiuroZCVevbvenbMBNM?7 (8534243 "3° 


abedefshk Jhb Jnknf rtewawryuyiurozcvevbvenbmbnm? (8534243 "3 / 


Example 3-2 Asynchoronous I/O Using Event Flags 


for Synchronization (Sheet 2 of 2) 
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USING THE QIO DIRECTIVE 
TERMINAL 1/0 


Device Specific Functions 


In the following discussion, references to function codes’ and 
subfunction codes are made via the global symbols used when 
programming in MACRO. This is done because all references in the 
literature to these codes use the MACRO symbols. Several examples 
of how to use these in FORTRAN programs are shown below. 


Some device specific function codes are listed in Table 3-3, shown 
below. Table 2-3 in section 2.3 (on the QIO macros) of the 
RSX-11M/M-PLUS I/O Driver's Reference Manual lists all of the 
available special functions for the full-duplex terminal driver. 
As noted, some of these functions are SYSGEN options. Many of the 
device-specific functions are selected using subfunction codes. 
These codes may be ORed with standard or device-specific function 
codes to produce special functions. For instance, the subfunction 
TF.TMO (read with timeout) may be ORed with a read function such 
as I0O.RLB to produce a function of "read logical block with 
timeout." 


The octal values for I0.RLB and TF.TMO are 1208 and 200, 
respectively; hence the combination of the two functions is 
represented by the octal value 1200. 


This can coded in FORTRAN as follows: 
CALL QIO("1L29D,errreee) 
or, to improve readability: 
INTEGER TFTMO 
DATA TFTMO/"200/ 
DATA IORLB/"1000/ 
CALL QIO(IORLB.OR.TFTMO,,,;,77,) 


Another way to produce this function which you may find simpler 
is: 


INTEGER RLBTMO 


DATA RLBTMO/"1200/ 
CALL QIO(RLBTMO,;r7777) 
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Table 2-4 in Chapter 2 of the I/O Driver's Reference Manual lists 
the various combinations which are possible. For example, TF.TMO 
(read with timeout) ORed with a read. function (IO.RLB, I0.RPR, 
IO.RNE, etc.) terminates the read if the specified time period 
goes by between keystrokes. For additional information on _ the 
device-specific function codes, see section Ze302 (on 
Device-Specific Functions) in the RSX-11M/M-PLUS I/O Drivers 
Reference Manual. Examples of the use of Read After Prompt, Read 
No Echo, and Read With Timeout are included in this module. 


Note that if you use subfunction codes with read or write function 
codes, you should use logical operations rather that virtual; 
i.e., use IO.RLB and IO.WLB rather than IO.RVB and IO.WVB. The 
reason for this is that when a virtual operation is requested on a 
terminal, the Executive converts the operation to a logical 
operation. In the process, any subfunction codes are lost. 


I/O Status Block and Terminating Characters 


As for other I/O functions, the low-order byte of the first word 
of the I/O status block contains the I/O status byte, indicating 
the success or failure of the I/O operation. Also, the second 
word contains the count of characters actually transferred. For 
reads from a terminal, the high-order byte of the first word of 
the I/O status block contains the terminating character in ASCII 
(<RET>, CTRL/C, etc.) for successful reads. Normally, CTRL/Z is 
treated as an error. The I/O status byte is set to IE.EOF (-19.) 
and the character count contains the count of characters” read 
before the CTRL/Z. 


Example 3-4, which follows, shows how CTRL/Z can be handled 
specially in a program. Two special function codes, I0.RST and 
IO.RTT, allow reads to be successfully terminated by nonstandard 
terminating characters. The first allows any non-alphanumeric 
character to terminate input; the second allows the user to 
specify which character or characters should terminate the read. 
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USING THE QIO DIRECTIVE 


Some Special Terminal Function Codes 


Global 
Symbol 


IO.RNE 


Octal 
Value 


081920 


Function 


Read With No Echo 


I/O Parameter 
List 


<stadr,size[,tmo]> 


IO.RPR 


IO.RST 


IO.RTT 


IO.WBT 


none 


GB440B 


GG1G01 


985001 


GBB50B 


81200 


(Same as IO.RLB!TF.RNE) 


Read After Prompt 


Read With Any 
Special Terminators 
(Same as IO.RLB! TF.RST) 


Read With Specified 
Special Terminators 


Write Logical Block, 
through ongoing I/O 
(Same as IO.WLB!TF.WBT) 
Task must be privileged 


Read With Timeout 


<stadr,size,[tmo], 
pradr,prsize,vfce> 


<stadr,size[,tmo]> 


<stadr,size,[tmo], 
table> 


<stadr,size,vfc> 


<stadr,size,tmo> 


(IO.RLB! TF.TMO) 
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Read After Prompt 


The Read After Prompt function allows the combination of a write 
of prompting text followed by a read in a single QIO request. The 
I/O parameter list contains six parameters, three for the read, 
and three for the write. The following notes are keyed to Example 
3-3. 


@ wToro for Read After Prompt. The function code is I0.RPR 
(4480 (8)). The first three parameters in the I/0 
parameter list are for the read, the last three are for 
the write. The write is performed first, followed by the 
read. The 44(8) for the vertical format control causes 
the prompt text to appear on the next line, followed 
immediately on the same line by the prompt for the read. 


(2 Use a normal FORTRAN WRITE to echo the input string. 


© If the operator types a CTRL/Z, an error status is 


returned. In this case, we just wish to exit normally. 
Therefore, we must check for this condition and handle it 
specially. 


The ability to use certain function codes, including Read After 
Prompt, is dependent on whether the option was included in the 
SYSGEN for your system. Before attempting to use these functions, 
check with your system manager to see if they'are available. 
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FROGRAM FROMFT 
C File FROMFT.FTN 


C This task issues ae QIO for READ AFTER FROMFPTs, echo’s it 
C and rromets aessain. This continues until @ CNTRL/Z is tured, 


tf 
BYTE FROMC22) ! Buffer for rromet strings 
RYTE BUFF (80>) ! READ buffer 
RYTE ITOSK(4) ! 1/0 status block 
INTEGER FARM(C4) 1 [7/0 Parameter block 
EQUIVALENCE (NCHARyITOSB(3)) !' NCHAR is for I/0 

oa ! count 
DATA PROM ! Fill the eromet buffer 
1 SOP 9 S19 @ yale Styl ery! Cy lhe uly om ye? 
2 if a ee a 0 DD i 
DATA IORFR /4"°4400/7 ! Read after rromet 

C ! 0 6funetion code 


C START? 
C Seto ur rarams. for Q10 


C° 

CALL GETADRCF ARM C1) »BUFFC1)>) !§ Pil is the address 
is i oof BUFF 

CALL GETADRCFARM(4)*sFPROM(1)> ! P4 is the address 
C lf of the eromet 


FARMC2) = 80 ! P2 is the lensth of 
06 6the buffer 
FARM(CS) = 22 | FS is the lensth of 
C: ! 0 6the Fromret 
FARM (C46) ' FS is the eromet 
! 06 6 format control 


tt 
inl 
th 


10 © CALL WTQIOCTORE RySvivyyTOSR»sPARMsTINS) | Invoke QIO 
IFC ImS .LT. O > GO TO 100 ! Directive error? 
IFC [TOSBC1) LT. O 9 GO TO 110 ! I/0 error? 


Cc 
6 WRITE (S915) (BUFF CT) »T=1.»NCHAR) ! Echo ineut 

C 1 6strins 

15 FORMAT( 1X+’You tured? “»80A1 ) ! FORMAT for 

C ! echo messade 
GO TO 10 1 Start over 

C° 

100 TYFE Ke “Directive error on QIO to REAL AFTER 
JPROMPT. OSW = “»T0S ! ftir error 


CALL EXIT 
C I/0 error. Check for “Z 


110 IF ¢ITOSB¢1) . EQ. -10) GO TO 150 ! Branch on “Z 
TYPE Ke “I/O error om QIQ to REA AFTER FROMFT. 
L USW = ’yTOSRC1) ! I/O error 

LSOQ CALL EXIT 
END 


Example 3-3 Prompting for Input (Sheet 1 of 2) 
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Run Session 


SRUN FROMF'T 

Please ture anything? sJkshJHGJHGHFY134435 
You tyred? sJkshJHGJHGHFY134435 

Flease tyre anything? hello there 

You tured? hello there 

Flease tyre anything? “Z 


o 


Example 3-3 Prompting for Input (Sheet 2 of 2) 


Read No Echo 


Read No Echo is used to override the default of echoing each 
character as it is typed. This is used for passwords and other 
private information. Example 3-4 uses this function. The 
following notes are keyed to the example. 


@ Write prompting text, then leave cursor at that position 
for input. This is done by having 'S$' as the first 
character in the FORMAT. 


Read No Echo QIO. Standard read parameters except for the 
function code. 


As in the previous example, we display the text typed in, 
preceded by our own message. Since the Read No Echo 
doesn't echo any characters back and hence doesn't move 
the cursor on the screen, we precede the text with a 
carriage return (15(8)) to get the cursor back to the 
Start of the line. Else, the NO LONGER A SECRET WORD 
message will begin away from the left-hand margin, after 
the : “SECRET WORD:". 
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FROGRAM NOECHO 
C File NOECHO.FTN 
This task feromets for ineutes reads it without echo and 


C then skies to the next line and diselays the inreut 
C text and exits. 


C 
C 
BYTE RUFF (80) »IT0S8(4) »CRC1) 
INTEGER FARM(C6) 
C 
ATA TORNE /*°01020/7 1 QO Read mo echo code 
VATA CR Z*157 |! Carriage return character 
t 
@ wRITE (ay) ! write rromet 
‘I FORMAT ¢’°$SECRET WORT? 73 ! FPromet strimns 


@ Set ur the 1/0 rarameter list 
CALL GETAIIR CPARMC1)*sBUFFC1)) l buffer address 
FARM(C2) = 80 i Buffer lensth 
C Issue read mo echo 
2) CALL WTQIO (TORNEsSyvissTOSBR»sFARM, TOS) 
IF (10S .LT. 0)? GO TO 160 ! ftir error? 
IF ¢€TOSB(1) .LT. O)> GO TO 110 i I/0 error? 
6 WRITE (S22) CRy CRUFF CIT)» T=19TOSEBC3)) § Echo ineut 


= -FORMAT ¢€/’ “sAls’NO LONGER A SECRET WORT? *»80A12 
CALL EXIT 

C° 

C Error conditions 

C 

100 TYPE xXx» “DTRECTIVE ERROR ON READ. STATUS = “s» TOS 
CALL EXIT 

L10 TYFE x&y “°T/70 ERROR ON REAM. COME = “»TOSBC(1) 
CALL EXIT ; 
END 


Rum Session 


“RUN NOECHO 
SECRET WORD? 
NO LONGER A SECRET WORD? ADD 


Example 3-4 Read No Echo 
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Read With Timeout 


Example 3-5 is a repeat of Example 3-1, but with a timeout on the 


read. 


The following notes are keyed to the example. Note 2 is in 


the run session. 


To invoke the timeout mechanism, TFTMO is ORed with the 


read function (IORLB). We must use Read Logical Block 
here, because any subfunction bits are stripped off when a 
Read Virtual Block is translated to a Read Logical Block 
function. In addition, the third parameter in the I/0 
parameter list specifies the length of the timeout in 
19-second intervals. This timeout occurs if that amount 
of time passes between successive keystrokes. If a 
timeout occurs, input is terminated, but no error is 
reported. Instead, the success code +2 is returned rather 
than the standard +l. . . 


In the first run, the QIO timed out after KJHKJj}j}. In 
the second run, the QIO was terminated with a carriage 
return before it timed out. 


To handle the timeout specially, just check the I/O status 
byte for a value of +2 (IS.TMO). Another alternative for 
placing a time limit is to use a Mark Time directive (CALL 
MARK). The timeout with a Mark Time is for the entire 
input, rather than for the next keysttoke. 
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USING THE QIO DIRECTIVE 


FROGRAM QILOTIM 
FILE QIOTIM.FTN 


This task reads ge line of text from the terminal» 
converts all ourrar case characters to lower casey and 
rerints the converted message back at the terminal. It 
uses synchronous QIlOss with @ timeout on the read. 


INTEGER ITOSB(2) »FPLISTC3) s0SWeDRCTYV 
RYTE BUFF C80) »SuCcCOn 
EQUIVALENCE (SUCCODyIOSB) |! Success code is low 
! pyte of I/0 status 
! 0 6hlock 
MNEMONICS 
INTEGER IORLE»yTFTMOs TOWVE 
QATA TORL Ey TFTMOs TOWVBS "10002 "200% "110007 
CALL GETADRCFLISTy BUFF) ! Fill in buffer address 
PLIST(2) = 80 ! Lensth of buffer 
FLIST(3) = J ! Timeout count 
G CALL WTQTOCTORLE.OR.TFTMOsSe1+°sTOSBeFLISTs DSW) 
! Issue read 
IF (QSW.LT.O0)} GOTO 1001 ! Branch om dir error 
IF (SUCCOD.LT.O) GOTO 1011 ! Branch on I/0 error 
NO 10 L=1sTOSRC2) ! Get count of characters 
fo 6tgred in 


Check for urrercase ASCII characters must be between A 
and Z ; 
IF (BUFF CIO.LT.’A’. OR. BUFF CI).GT.°Z’) GOTO 10 
It is wurerer caser so convert 

BUFF CDT) = BUFF CDI+32 

CONTINUE 

FPLISTC2) = TOSBC2) ! Cheracter count and 

PLISTCS) = "40 ! Format control for 

Po guteut 
CALL WTQTOCTOWVEsSylevyTOSRyPLIST»sOSW) § Outeut 
| results 

IF (OSWw.h?.0) GOTO 1002 ! Branch on dir error 

IF ¢SuUCCOO.LT.O) GOTO 1012 ! Branch on I[/0 error 

CALL EXIT 


Example 3-5 Read With Timeout (Sheet 1 of 2) 
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C 


101 


1002 
1003 


1004 


LOL 


O12 
LOLS 
LOL4 


USING THE QIO DIRECTIVE 


C Error code 
Cc 


QRCTV = 1 
GOTO 1003 
DRCTV = 2 
TYFE 1004eDRCTV»0SW 


FORMAT ¢/ DIRECTIVE ERROR 


1 DSW =’9Td4) 
CALL EXIT 


QROTY = | 
GOTO 1013 
IRCTY = 2 


TYPE LO14%DRCTVsTIOSBC(1) 


Error om ist QI0 
Print MeSsadce and exit 
Error on 2nd Qr0 


ON DIRECTIVE #%/9Tay/ » 
Error on ist QI0 


Frint message and exit 
Error om 2nd QI0 


FORMAT ¢¢’ I/0 ERROR ON DIRECTIVE #’9T29’%» I/O 


LCODE =’ sT6) 
CALL EXIT 
ENIi 


Kun Session 


“RUN QIOTIM 


KJHK Jd 


bk Jk J 


=RUN QIOTIM 
JJJafik jfiurcReT> 
wa Phhk JP iar 


“ 


Example 3-5 
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USING THE QIO DIRECTIVE 


Terminal-Independent Cursor Control 


Terminal-independent cursor control is provided if selected at 
SYSGEN time. If this is done, certain I/O requests are 
automatically converted for you by the terminal driver for’ the 
particular device for which the I/0 request is made. This is 
typically done with escape sequences used for positioning the 
cursor. This allows a task to move the cursor to any position on 
the screen and then write a message. This also-can be done by 
imbedding the terminal-specific escape sequences into the write 
buffer. The advantage of using terminal-independent cursor 
control is that the same program will work at different terminals 
(VT-52s and VT-10@s, for example), without any need for 
modification. | 


To provide cursor control, place the proper value in the vertical 
forms control word of the I/O parameter list. If the high-order 
byte in the VFC word is nonzero, the word is interpreted as a 
cursor position. The high-order byte is the line number, and the 
low-order byte is the column number. Home poSition, the upper 
left corner of the screen, is defined as line 1, column 1. To 
start the display at line 18, column 25, place a 1@ in the 
high-order byte and a 25 in the low-order byte. To do this, use 
the expression 19*256.0R.25. In general, X*256.OR.Y corresponds 
to position X,Y on the screen. If the high-order bit in the line 
number byte is set, the screen is cleared before the cursor is 
moved. 
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USING THE QIO DIRECTIVE 


3-6 demonstrates the use of terminal-independent cursor 
The following notes are keyed to the example. 


Issue a Mark Time directive. In the CALL MARK(3,1,3,DSW), 
the first parameter is EFN 3. The 1 is the time interval 
magnitude. The second 3 is the time interval unit. A 3 
indicates minutes. Hence the directive will set EFN 3 in 
one minute. 


Issue the second Mark Time directive. This one will set 
event flag 2. It is used as the time interval for 
updating the time. When the one second goes by and_ the 
flag is set, we check for one minute gone by and update 
the time display again if it has not. 


Put the address of TIMMSG into PLIST(1l). 


Put X (line) in high byte and Y (column) in low byte of 
PLIST(3), which is the vertical forms control for a QIO. 
When the high-order byte of the VFC is nonzero, the word 
is interpreted as a cursor position. 


Issue the write. The vertical format control (X*256).OR.Y 
places the cursor before the write at line X, column Y. 
The TF.RCU subfunction code (TFRCU) instructs the terminal 
driver to save the cursor position before moving it and 
then to restore it after writing the Message. This allows 
an operator to continue typing in commands while this task 
runs. 


Wait for one second to go by. 


Read event flag 3. If it is set, the one minute is up and 
we should exit. 


The display will actually appear at line xX, column Y on _ the 


screen, 


and is updated every second. 
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FROGRAM DATTIM 
C+ 
C FILE DATTIM.FTN 


C This task elaces the date and the time at line Xy» 
( column Y and then uedates the disrelay every Z seconds 
C for 1 minute. 
C- 
INTEGER Xs¥o9Z 
QATA X9V¥rZ/S¥ 32917 
INTEGER USW»yTOSK(2) sFLIST(S3> 
BRYTE SUCCOD:s TIMMSG¢(18) 
EQUIVALENCE (SUCCOD»TOSB? ! Low bute of status 
C ! block is success code 
INTEGER TOWLBsyTFRCUsTSCLA 
VATA TOWLBs TFRCUs ISCLR/ "40091207 
@ CALL MARK (Sy 1939 0SW) ! Set ur to exit after 
! 1 minute 
IF (OSW-eLT.O) GOTO 1001 ! Branch on dir error 
10 6 CALL MARK (292922 T0SW) | Set event flas 2 after 
! 2 seconds 
IF (OSW.LT.O)} GOTO 1002 
CALL DATECTIMMSG 
TIMMSG(10) = 7 * 


1 Get date in bytes 1-9 
! Insert srace hetween 
! gate and time 
CALL TIMECTIMMSGC1193 ! Get time in bute 11-18 
3) CALL GETADRCPLIST»sTIMMSG) 
FLISTC2) = 18 
© FLIST(3) = (X#256).0R.Y 
” Uiarelay time 
6 CALL WYQIQOCTOWLB.OR.TFRCUsSyissIOSB»FPLISTs SW) 
IF (YSW.LT.0O2 GOTO 1003 ! Branch on dir error 
IF (SUCCON.LT.»G) GOTO 1004 ! Branch on I70 
! error 
1 Wait for mark time to 
[ @xMrire 
! Branch om dir error 


a“ 


© carte wartFrR«2snsw) 


IF (YSW.LT.O) GOTO 1005 
(] Check for 1 mirwte gone by 
7 ) CALL REAQEF ¢(3»0SW) ! Check event flas 
TF (nSW.LT.O0)? GOTO 1006 ! Branch on dir error 
IF (NSWeEQ.ISCLR) GOTO 10 ! Check for fleas 
! glready clear. If 
1 clears minute 
3 fo oU6natouur vety update 
! disrlay ssain 
GOTO 1100 


Example 3-6 Terminal-Independent Cursor Control (Sheet 1 of 
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2) 


USING THE QIO DIRECTIVE 


G Error code 


1001 WRITE (S91051) oS 
GOTO 1100 
LQ02 WRITE (Sv1lOS2) Sw 
GOTO 1100 
1003 WRITE (S91053) usw 
GOTO 1100 
LO04 WRITE (S»1054) SUCCOD 
GOTO 1100 
1005 WRITE (S91l055) DSW 
GOTO 1100 
1LOO6G WRITE (S91056) DSW 
GOTO 1100 
LOS1 FORMAT (¢’ ERROR ON MARK TIME FOR 1 MINUTE. DSW = 
1 ’9IS) 
1032 FORMAT ¢(’ ERROR ON MARK TIME FOR 1 SECOND. [SW = 
Lb ’y9IS) 


10533 FORMAT ¢¢ DIRECTIVE ERROR ON WRITE. [SW = ’»ITS) 
1054 FORMAT ¢° I/0 ERROR ON WRITE. CODE = “’»I3) 
LOSS FORMAT ¢’ ERROR ON WAIT FOR. DSW = “’»I5) 
L056 FORMAT (’ ERROR ON CLEAR EVENT FLAG. DSW = ‘9»IS) 
1100 CALL EXIT 

END 


Run Session 


12-MAR-82 11°12354 
=RUN DATTIM ! NISPLAY WILL START AT LINE Sy» COLUMN 32 


Example 3-6 Terminal-Independent Cursor Control (Sheet 2 of 2) 


Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all lab problems. Check your answers against the 
solutions provided, either in that book or in on-line files. 


If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, return 
to this module for further study. 


99 


USING DIRECTIVES FOR 
INTERTASK COMMUNICATION 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


INTRODUCTION 


The RSX-11M program development features allow modular development 
of programs; the multitasking feature allows a modular approach 
to applications. 


A system of multiple tasks may require one or more of the 
following services provided by executive directives under RSX-11M. 


e First task requests that the second task be run. 


e First task is notified of completion of the second task 
operation. 


e Tasks pass data to each other. 


This module explains how to use system directives for this type of 
coordination between tasks. 


OBJECTIVES 


e To use directives which control task execution to 
synchronize cooperating tasks 


e To use the send/receive directives to pass data between 
tasks 


e To write tasks which spawn subtasks using parent/offspring 
directives 


RESOURCE 


e RSX-11M/M-PLUS Executive Reference Manual, Chapters 2 and 
4 plus specific directives in Chapter 5 
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USING TASK CONTROL DIRECTIVES AND EVENT FLAGS 


It is generally good programming practice to divide a single 
complex task into a number of separate tasks, with each task 
performing a distinct logical function. The use of a group of 
tasks to perform a complex function frequently makes good sense, 
especially where different parts of the process may run at widely 
differing speeds, each more or less independent of the others. 


Suppose, for instance, that one needs to simulate customer 
transactions at a bank. There are, say, five windows and up to 15 
customers can physically stand in line at a time, given the _ size 
of the waiting area. One might design a group of tasks, one task 
per line, to Simulate this complex system. This approach has-7~ the 
advantage of simulating the related, but essentially parallel, 
processes in a more realistic manner than would a single, serial, 
Simulation. A further advantage of a multitasking approach to 
such a job is that changes in the behavior of the system that are 
caused by changes in a single line (e.g., by assigning different 
sorts of transactions to different lines) can be easily simulated 
merely by modifying the task that simulates that line. 


An RSX-11M programmer typically uses a mix of four multitasking 
methods: . 


e Common or group global event flags, together with 
synchronization and task scheduling directives, are used 
to synchronize tasks. 


e Resident commons are used to share data in memory. 


e Memory management directives are used to create and/or 
share data areas dynamically at run time. 


e File handling routines are used to open disk files for 
shared access. 


The use of shared regions, memory management directives and files 
are covered in later modules. 
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Directives 


Table 4-1 lists the various task control directives which are 
available for task synchronization. Most of them were discussed 

in earlier modules. All of the directives are documented 
individually in Chapter 5 of the RSX-11M/M-PLUS Executive 
Reference Manual. - . a 


Table 4-2 shows the differences between suspending and stopping a 
task. The major difference is that stopping puts the task into a 
Stopped state which effectively lowers the task priority to @, 
allowing any active task to checkpoint it if it is checkpointable. 
Suspending or waiting, on the other hand, keeps the task competing 
for memory space on the basis of its running priority. This means 
that if the task is checkpointable, only tasks of higher priority 
can checkpoint Lea: Waiting for an event flag affects 
checkpointability the same way as suspending. 


Table 4-3 lists the various event flag directives which are 
available for synchronization. : 
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Table 4-1 Task Control Directives 
and Their Use for Synchronizing Tasks 


Directive Example of Use for Synchronization 
FORTRAN CALL 
REQUES Issuing task activates target task; 


RUN target task then performs some operation 
for issuing task 


ABORT Issuing task aborts target task 
SUSPND A task suspends or stops itself to 
STOP wait for completion of another 


task operation 


A task suspends or stops itself 
until it is needed by another task 


RESUME A task resumes or unstops another 
USTP task which has suspended or stopped 
; itself while waiting for it 
to complete some operation 


A task resumes or unstops another 
task when it needs the other task's 
services 


A task can also be resumed: 
- by its own AST routine 
-~ by an operator using a DCL CONTINUE 
command (RESUME in MCR) 
A task can also be unstopped: 
- by its own AST routine 


- by an operator using a DCL START 
command (UNS in MCR) 
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Table 4-2 Stopping Compared to Suspending or Waiting 


Stopping 


Priority is effectively 
dropped to @ 


Task can be checkpointed 
by any other task (if 
checkpointable) 


Likelihood of being 
checkpointed increases. 


Frees memory for other 
tasks 


Task response time 
increases dramatically 
if task is checkpointed 


Suspending or Waiting 


Priority remains unchanged 


Task can be checkpointed 
only by tasks of higher 
priority 


Likelihood of being check- 
pointed remains normal 


Continued allocation of 
memory can block out lower 
priority tasks 


No change in task response 
time, because no change 

in likelihood of being 
checkpointed 
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Table 4-3 Event Flag Directives and 
Their Use for Synchronizing Tasks 


FORTRAN CALL 


CLREF 


SETEF 


WAITFR 
STOPFR 


STLOR 
WFLOR 


READEF 


Example of Use for Synchronization 


A task clears the event flag, then waits 


for it to be 


set by another task 


A task performing an operation for 


another task 


sets an event flag to 


signify completion of the operation 


A task waits 
operation by 


for completion of an 
another task by waiting 


or stopping for that task to set an 


event flag 


A task waits 
of the first 


A task tests 
operation by 


or stops for the completion 
of some set of operations 


for completion of an 
another task, without 


waiting or stopping for it 
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Example 4-1 shows the use of the Request Task (REQUES), Suspend 
(SUSPND), and Resume (RESUME) directives for synchronization. The 
following notes are keyed to the example. Notes 1,2 and 5 are in 
TASKA. Notes 3 and 4 are in TASKB. : 


@ TASKA requests TASKB. This means that TASKB must be 
installed under the name TASKB. After this, both tasks 
are active and compete for memory and CPU time. | | 


@ TASKA suspends itself. After this it still competes for 
memory at its regular priority, but not for CPU time. 


© TASKB types out a message and then resumes’ TASKA. More 
typically, TASKB would perform some. service for TASKA 
rather than just typing a message, After TASKB- resumes 
TASKA, they both compete for CPU time again. 


4 | TASKB displays another message and then exits. 
6 TASKA, now resumed, displays a message and exits. 
Depending on the relative priorities of TASKA and TASKB and on the 


particular task scheduling options on your system (e.g., round 


robin scheduling, etc.), steps 4 and 5 may be reversed on the 
run session. 
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FROGRAM TASKA 
( FILE TASKA.FTN 


C This task reauests TASKE to runs and then susrends 
C itself. TASKE resumes this task and exits. 


C Install and rum instructions? TASKA and TASKE must he 
C anstelled. Just rum TASKA. 


INTEGER 0S 
IATA TASKE/SRTASKE/ 


TYPE X»’TASKA BEGINS AND REQUESTS TASKER’ 
CALL REQUES (CTASKEs » NSW) 
IF (OSW.LT.O) GOTO 900 


TYPE x»“TASKA IS SUSPENDING ITSELF ’ 
@ car. susenocusw> 
IF (0SW+LT.0) GOTO 910 


5) ee Kk» “TASKA HAS BEEN RESUMED‘ 
CALL EXIT 
900 TYFE x» “TASKA UNABLE TO REQUEST TASKER. SW = 
Le tSW 
GOTO 1000 
F10 TYPE x» ‘TASKA UNABLE TO SUSPEND. DSW = ’»DSW 
1000 CALL EXIT 
END 


Example 4-1 Synchronizing Tasks Using Suspend and Resume 
(Sheet 1 of 2) 
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FROGRAM TASKE 
C FILE TASKE.FTN 
C This task is activated pny TASKA. It rerforms its 
> oreration and resumes TASKAy which has susrended 
C itself. 


INTEGER DSW 
QNATA TASKA/SRTASKA/ 


C 
C START? 
C AnvY Oreration could be rerformed heresy but in this 
C case it’s only @ tyreout. 
GC 
3) ee Ky’TASKE IS ALIVE AND RUNNING’ 
CALL RESUME CTASKAs TSW) 
IF (YSW.LT.O) GOTO 300 
TYPE *»“TASKE HAS RESUMED TASKA ANI IS EXITING’ 
CALL EXIT 
900 TYPE x*»’TASKB UNABLE TO RESUME TASKA. TSW = ”% »lSW 
CALL EXIT 
ENT 


Rum Session 


“INS TASKA 
“INS TASKB 
“RUN TASKA 


TASKA BEGINS ANID REQUESTS TASKER 
TASKA IS SUSFENDING ITSELF 
TASKE ITS ALIVE AND RUNNING 
TASKA HAS BEEN RESUMED 
TASKB HAS RESUMED TASKA ANT IS EXITING 


Example 4-1 Synchronizing Tasks Using Suspend and Resume 
(Sheet 2 of 2) 
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Example 4-2 shows the use of event flags for synchronization. In 
Module 2, there is a similar example. Here, TASKC requests TASKD, 
rather than requiring an operator to start both tasks. Also, Stop 
For Single Event Flag is used rather than Wait For Single Event 
Flag. The difference between the two is that the first causes the 
task to enter a stopped state and the other causes the task to 
enter a Wait For (like a suspended) state. The following notes 
are keyed to the example. Notes 1,2,3 and 6 are in TASKC. Notes 
4 and 5 are in TASKD. 


@ clear the event flag to initialize it. It's initial state 
is unpredictable, since other tasks may have set or 
cleared it. 

Request TASKD. 

Stop until the event flag is set by TASKD. 

TASKD displays a message and sets the event flag. 


TASKD displays a message and exits. 


TASKC displays a message and exits. 


Depending on the relative priorities of the two tasks, significant 
events in the system, and other scheduling considerations, the 
order of the steps may vary. In particular, steps 3 and 4 
above may be reversed, as well as 5 and 6. 


The event flag must be a common or group global, and not a local 
one. In either case, the users on the system must coordinate to 
avoid several users using the same event flag for different 
purposes. If a group global event flag is used, the flags for 
that group may have to be created using either the Create Group 
Global Event Flags directive (CRGF) or the DCL SET 
GROUPFLAGS/CREATE (FLA /CRE in MCR) command. 


The Executive only scans the Active Task List and schedules’ tasks 
for CPU time after a Significant event. Setting an event flag 
does not cause a significant event. This means that TASKC 
normally won't compete for CPU time until at least the next 
Significant event in the system. If it is important that TASKC 
being executing sooner than that, TASKD should issue the Declare 
Significant Event directive (DECLAR), causing the Executive to 
reschedule tasks. For a discussion of significant events, see 
Chapter 2 of the RSX-11M/M-PLUS Executive Reference Manual. 
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FROGRAM TASKC 


C FILE TASKC.FTN 


C This taste 


clears an event flags and reauests TASKI to 


CO runny and then stores until the event flags is set by 


® TASKD 


C Instell and run instructions? TASKED must be installed. 
OC Just rum TASKC, 


| 


INTEGER TISWy»yFLAG 
ATA FLAG/33/ I!MNEMONIC FOR EVENT FLAG 
ATA TASKI/SRTASKDZ 


*»’TASKC BEGINS AND REQUESTS TASKI’ 


CLREF (FLAG » TSW) 


IF (OSW.LT.O) TYPE x» ’TASKC UNABLE TO INITIALIZE 
TEVENT FLAG. DSW = “sDSW 


@ cart REquEScTasKn, snSsu) 
IF (USW.LT.O) TYPE *»/TASKC UNABLE TO REQUEST 
1TASKE. DSW = / DSW 


Ky ’“TASKC IS WAITING FOR EVENT FLAG’ 


6 CALL STOPFRCFLAGsISW) 
IF (OSW.LT.O) TYPE x» ’TASKC’’S WAIT REQUEST 
LREJECTED. DSW = “ssw 


c: 

C 
TYPE 

C 
@ ca 

C 

C 
TYFE 

C 


TYFE X»’TASKC HAS BEEN UNSTOFPED ANTI WILL NOW 


© |1exir’ 


CALL EXIT 


ENT 


Example 4-2 


Synchronizing Tasks Using Event Flags 
(Sheet 1 of 2) 
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FROGRAM TASKED 
(FILE TASKILFTN 


C Tnis task is activated by TASKC. It rerforms its 
( orersation and sets the flas for which TASKC is waiting 


INTEGER UISWs FLAG 

LATA FLAG 337 IMNEMONIC FOR EVENT FLAG 
C START? 
C AnY Oreration could be vrerformed heres but in this 


CO case it’s onls &@ tyreaout. 


TYFE Ky “TASKO IS ALIVE AND RUNNING’ 
= SETEF (FLAG sDISW) 
(iSW.LT.O) TYPE x» “TASK UNABLE TO SET EVENT 


iFLAG. boy = / rDgw 
YPE SK0 HAS SET THE EVENT FLAG ANID IS 
5) [rexrri IT Nee 
YALL EXIT 
ENO 5 


Rur Session 


SINS TASKC 
*RUN TASKC 
TASKC BEGINS ANDI REQUESTS TASK 
TASKC IS STOPPING FOR EVENT FLAG 
TASKE IS ALIVE AND RUNNING 
TASK. HAS SET THE EVENT FLAG AND IS EXITING 
TASKC HAS BEEN UNSTOPFED AND WILL NOW EXIT 


Example 4-2 Synchronizing Tasks Using Event Flags 
(Sheet 2 of 2) 
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SEND/RECEIVE DIRECTIVES 


General Concepts 


The Send and Receive directives are used to transmit a 13 word 
block of data between tasks. The sequence of events is as 
follows: 


1. <A task issues a Send Data request, specifying a receiver 
task and a data buffer. 


2. The Executive copies the data buffer into a data packet in 
the dynamic storage region (DSR or pool). 


3. The Executive places the data packet FIFO 
(first-in-first-out) into the receive queue of the 
specified receiving task. 


4. Later, the receiving task issues a Receive Data request, 
specifying a data buffer. 


5. The Executive copies the data packet into the buffer 
specified by the receiving task. 


Directives 


Table 4-4 lists the Send Data directive and the various Receive 
Data directives. The difference among the Receive Data directives 
concerns what happens if there are no data packets in the 
receiver's receive queue. 


All receive directives receive 15(18) words, including the sender 
task name (in Radix-5@ format) plus the data. If no sender task 
is specified in a Receive Data directive, the first packet in the 
receive queue is dequeued, regardless of which task sent it. If a 


sender task is specified, only a packet sent by that task is 
dequeued. 


116 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


Table 4-4 


Directive 


Directive 


The Send/Receive Data Directive 


Name Call Notes 

Send Data SEND Sends a 13(1@8@) word 
buffer to receiver 
Event flag (if used) 
set when packet queued 
to receiver 

Receive Data RECEIV Error if no data 
packets queued 

Receive Data RECOEX Exit if no data 

or Exit packets queued 

Receive Data RCST Stop if no data 

of Stop packets queued 


Synchronizing Send Requests With Receive Requests 


Event flags can be used for synchronization. The event flag is 
specified by the sending task. This event flag is set when the 
data packet has been queued to the receiving task. Thus, a global 
or group global event flag may be used to unblock a receiving task 
which is active and waiting for the event flag to be set. 


In addition, the task control directives can be used for 
synchronization. Table 4-5 summarizes the various synchronization 
techniques which might be used. Keep in mind that a Receive Data 
directive (RECEIV) causes an error condition (DSW = -8, IE.ITS; 
directive inconsistent with task state) if there is no data packet 
in the receive queue, Receive Data or Stop (RCST) and Receive 
Data or Exit (RECOEX), on the other hand, cause the task to_ stop 
or exit, respectively, if there is no data queued. For further 
information about. possible synchronization problems, see the 
writeup on the Receive Data directive (RECEIV) in Chapter 5 of the 
RSX-11M/M-PLUS Executive Reference Manual. 
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Table 4-5 Methods of Synchronizing a Receiving Task 
(RECEIV) with a Sending Task (SEND) 


Method 


RECEIV issues a Wait 
For or a Stop For 
Event Flag directive, 
followed by a Receive 
directive. SEND uses 
that (common or group 
global) event flag in 
its SEND directive. 


RECEIV issues a 
Suspend or a Stop 
directive followed 
by a Receive direc- 
tive. SEND issues a 
Send directive 
followed by a Resume 
or an Unstop 
directive. 


RECEIV issues a 
Receive Data or Stop 
directive. SEND issues 
a Send followed by an 
Unstop directive. 


RECEIV monitors an 
event flag periodi- 
cally. When the 
event flag is set, 
RECEIV issues’ the 
Receive directive. 
SEND specifies that 
event flag in its 
Send directive. _ 


Advantages 


Low system scheduling 
overhead. 


Does not require an 
event flag. 


Low system scheduling 
overhead. 

Does not require an 
event flag. 


RECEIV can continue 
processing in para- 
llel with RECEIV. 


118 


Disadvantages 


Requires care in 
initializing and 
setting flag. 

(See Examples 4-3 . 
and 4-4.) 


Possible problems 
in sequence of 
Suspend or Stop, 
and Resume or 
Unstop, if the 
Resume Unstop is 
issued before the 
receive suspends 
or stops. 


Possible delay 
starting RECEIV 
again, if RECEIV 
was checkpointed. 
(Can be avoided 
if RECEIV is 
built non-check- 
pointable.) 


RECEIV must 
periodically re- 
issue a Read 

Event Flag or 

Clear Event Flag 
directive. Requires 
care in initiali- 
zing and setting 
the flag. 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


Examples 4-3, 4-4, and 4-5 show the use of Send and Receive 
directives by a pair of tasks. Examples 4-3 and 4-4 use an event 
flag for synchronization; Example 4-5 uses Receive Data or Stop 
along with Unstop for synchronization. The following notes are 
keyed to Example 4-3. Notes 1, 5, 6 and 7 are in SEND1l. Notes 2, 
3, 4, 8, 9 and 1@ are in RECV1. 


C1] RECV1 must be run first, or else the event flag will 
already be set by SEND1 to indicate that a data packet has 
been sent. In that case, RECV1 will clear the flag and 
wait for it to be set again, and won't realize that a data 
packet is already queued to it. 


Use a DO loop with "I" as the message counter. We will 
receive and display three messages and then exit. 


Initialize the event flag. 


Wait for the flag to be set after SEND1 sends the data 
packet, placing it in RECV1's receive queue. 


Get the data to be sent. 


Send the data and set event flag 33 when the data packet 
is queued to RECVI. 


SEND1 exits. 


Receive data from anyone. 


Display a header and the data sent. We skip the first two 
words (four-bytes) of the buffer, which contain the name 
of the sender task in Radix-5@ format. 


Go through the loop which clears the event flag and 
receives again if we have not yet received three messages. 
If we have, display a message and exit. 


3 ) 


119 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


FROGRAM SEND 
> FILE SENDL.FTN 


” This task eromets at TI? for @ line of text and sends 
. the data to RECVI for rrocessing. . Synchronization is 
CG handled through 8s common event flags. f 


( Inetall and run instructions? RECVL must be installed 
@ > and run Prior to running SENDL. RECVI continues to run 
7 umtil it receives 3 data rackets. 


C; 

BYTE BUFFER(C26) 
HATA IEFN /33/7 ! Event flas 
NATTA RTASK/SRRECYVI 7 ! Receiver task 


C Fromet for inert 
5 TYPE xX» ’TYFE A LINE OF TEXTs 26 CHARACTERS OR LESS’ 
READ (S910) BUFFER ! Read text 
10 FORMAT (26A1>) 
CALL SEND CRTASKsBUFFERYTEFNeyI0SW) |! Send date 
fe 7) IF CInSW .LT. O) GOTO 900 ! Branch on dir error 


CALL EXIT ! Exait 

C Error code 

900 TYFE xX» “UNABLE TO QUEUE DATA TO RECVi. DSW = “sInSsw 
CALL EXIT 
END 


Example 4-3 Synchronizing a Receiving Task Using Event Flags 
(Sheet 1 of 3) 
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FROGRAM RECV1 
C FILE RECV1I.FIN 
C This task receives data from any sender task Ce...» 
C RECVLI. It erints the data on TI3. Then it waits for 


CG another data racket. It does this until it has received 
C 3 messages and then exits. 


C This task syunmchronizes with its sender through an 
~ CC event fles. 


C Install and run instructions? RECVL must he installed 
C and run before runnins SENT. ; 


(0 
INTEGER RBUFF CLS) ! Receive nuffer 
DATA TEFN /33/ ! Event flag 
C 
6086 NO 100 T=193 . 
CALL CLREF ¢€33»T0SW) i Clear flag 


IF (10SW .GE. 0) GOTO 106 
TYFE X» “ERROR INITIALIZING FLAG. DSW = ’sTOSW 
GOTO 1000 

10 6 CALL WAITFR ¢(33»T0SW) | Wait for a send 

IF (I0SW .EQ. 1) GOTO 20 

TYFE X»’WAIT DIRECTIVE FAILED. DSW = “’»TOSwW 

GOTO 1000 

20 rs) CALL RECEIV (CsRBUFFysTI0SW) ! Receive from anyone 
IF (TOSW .EQ. 1) GOTO 30 
TYPE X» “RECEIVE DIRECTIVE FAILED IN "RECVI". 
1 USW = “sTTSw 
GOTO 1000 

30 ol Ke ‘DATA RECEIVED BY "RECVI"? 7’ 
WRITE (3935) (RBUFF CK)» K=3915) 

3S FORMAT ¢€% “’913A2) 

100 @ CONTINUE 
TYFE xk» ’"RECV1" HAS RECEIVED 3 MESSAGES AND WIL. 
1 NOW EXIT’ 

1.000 CALL EXIT 
EN 


Example 4-3 Synchronizing a Receiving Task Using Event Flags 
(Sheet 2 of 3) . 
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Rum Session 


2INS RECVI 

RUN RECVI 

“RUN SENDA 

TYPE A LINE OF TEXTs 26 CHARACTERS OR LESS 
BLLL114 

NATA RECEIVED BY "RECVI"3 


“444414 

“RUN SEND 

TYPE A LINE OF TEXT» 26 CHARACTERS OR LESS 
rye “ye 


Cal a a rR 


2 
Bee Wen Bee 


ATA RECEIVED BY "RECVI"3 


8 8 8222222 
Bee Res Aes Bee Bes Ase Boe dive Ase deve 


2RUN SENDA 
TYPE A LINE OF TEXT» 26 CHARACTERS OR LESS 
3333333333333333333333333 | 

NATA RECEIVED BY “RECVI": 


" 3333333333333333333333333 
"RECV1" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 


Example 4-3 Synchronizing a Receiving Task Using Event Flags 
(Sheet 3 of 3) 
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If you wish to run the tasks in Example 4-3 in any order, RECV1 
must be modified to receive data packets on startup if SENDI1 has 
already sent data. It gets complicated because SEND1 may have 
already sent several data packets. It's also possible that event 
flag 33. was left set by someone else. In that case the Receive 
directive will fail, but we should not abort. Example 4-4 shows 
the modifications which must be made to Example 4-3 to allow the 
tasks to be run in any order. The following notes are keyed to 
Example 4-4. 


@ We use a flag word (IBEF) to distinguish whether we are 
working on messages sent before or after RECV1 starts up. 
Note that RECV1S must be installed as RECV1, since SEND1 
sends to RECVI. 


@ Check for event flag set on startup. If it is set, issue 
a Receive. If SEND1 has been run one or more times, the 
Receive will succeed. If SEND1 has not been run yet, the 
flag was set by another task and the Receive will fail. 


© If the flag was not set, SEND] hasn't sent any messages 
before we started. Clear the IBEF flag, so we know that a 
Receive failure after the flag is set again is a real 
failure. : 


4 | In the case of a Receive failure, we check to see if we 
are receiving data packets sent before RECV1 started up. 
If we are, we Know we have received all data packets 
already queued up before RECV1 started executing. 


5 If IBEF is clear, this was a failure after receiving all 
data packets sent before RECV2 started up, so display an 
error message and exit. 


6) If IBEF is set, we have already received all data packets 
which were queued up before RECV1 started up. Now clear 
IBEF and wait for the flag to be set at 49@. 


@ Check to see if we are still receiving data packets’ sent 
before RECV1 started up. If so, Receive again. Keep 
receiving until either we get all three packets or we get 
a Receive failure. If, on the other hand, we have 
received a message sent Since startup, clear the flag and 
wait for it to be set again when a new message is sent. 


If a task runs and then exits with data packets in its' receive 
queue, those unreceived data packets are flushed from the queue on 
exit. Hence, if SEND1 sent four messages before RECV1l was run, 
the fourth message would be lost. 
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FROGRAM RECVIS. 
C FILE RECVIS.FTN 


( This task and receives data from anv sender task. 
(@ C@esgs SENDI). It erints the data on TIt. Then it 
@ waits for another data racket. It exits after 

C receiving and diselaving 3 messaeses,. 


C This task synchronizes with its sender through an 

C event flags. Because of this synmchronizations and the 
( care we take on startur to set messages already 

CM gents the tasks can be run in any orders with any 

C relative rriorities. 


CG Insetell and run instructions? RECVLS must be instelled 
CGC under the mame RECYVIL to work with SENT. 


@c ser is the "before" flass used to keer track of whether 
C we gre receivins messages sent before RECV1 started ur. 
C If the event fleas is set at startur times keer receiving 
C messades until we set a failure. We then wait until the 
C fleas is set to receive esain. 1 means receiving messases 
C sent hefore RECVI starteds O means finished receiving 
C messases sent hefore 

INTEGER el ee ered oa 


QATA IEFN /33/7 Event flag 

QATA IBEF /1/ ) Refore flasy assume 
C ! there Bre messases 

IATA MONT 7/37 ! Messade counter 


CALL CLREF CIEFN»sI0SW)> 
6 IF ¢10SW .LT. 0) GOTO 900 ! Branch on dir error 
IF ¢(InNSW .EQ. 2) GOTO 50 ! Branch if fleas set 
CG Here if flas mot initially set 
IF (IBEF .EQ. 0) GOTO 40 
IBEF=9 1 0 hefore flas 
40 CALL WAITFR (33%sT0SW)> ! Wait for next messase 
IF ¢€I0NSW .LT. OF GOTO 910 ! Branch on dir error 
C Get here when the flas is set 
830 CALL RECEIV ¢CsRBUFFs»I0SW) !§ Receive from arnsoane 
IF (InSW .EQ. 1) GOTO 80 ! Branch on directive ok 
@ Here on failure of Receive directive 
IF CIBEF .EQ. O) GOTO 920 ! Check for failure 
- . ! on messases received 
C ! before startur. 
C Here if failure after receiving messages already there 
C at startur 
IBEF=0 ! Clear before fla¢ 
GOTO 40 ! Wait for flas to he set 


Example 4-4 A Receiving Task Which Can be Run Before or After 
the Sender (Sheet 1 of 3) 
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C Successful receifet 


80 


TYPE Ky ‘DATA RECELVED BY "RECVI"$/ 
WRITE (Sv85) (CRBUFF CR) yK=3 215) 


a5 @|rormat c¢ 791302) 


{ Set 


C Here 


100 


MCNT=MCONT~ 1 ! Lecrement message counter 
IF (MCNT .EQ. 0) GOTO 100 ! Branch back if mot done 
ur for another receive 
IF ¢(IBEF .NE. 0) GOTO SO ! Check for still 
i receiving messages sent 
1 before startur. If soy» 
! receive assfsaim. 
CALL CLREF (33» T0SW) ! If mots clear flas 
IF ¢(IT0SW .LT. 0) GOTO 930 ! Branch on dir error 
GOTQ 40 ! Wait for flast set asain 


when three messages received 

TYFE Ky’ "RECVI" HAS RECEIVED 3 MESSAGES AND WILL 
1 NOW EXIT’ 

CALL EXIT 


C Error code 


900 
910 


920 


930 
L000 


Example 4-4 


TYPE X»’ERROR INITIALIZING FLAG. DSW = “+s Ins 
GOTO 1000 

TYFE X»’WAIT DIRECTIVE FAILED. OUSW = ’»TDSW 

GOTO 1000 

TYPE XK» “RECEIVE DIRECTIVE FAILED (IN "RECVi". 0SW 
1 = ‘»Tnsw 

GOTO 1000 

TYPE ¥» “ERROR RECLEARING FLAG. DSW = “’» TSW 

CALL EXIT 

ENIt 


A Receiving Task Which Can be Run Before or After 
the Sender (Sheet 2 of 3) 
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Run Session 


SINS/TASK.NAME SRECVL RECVIS 

SRUN SENDAI 

TYPE A LINE OF TEXTr 26 CHARACTERS OR LESS 
Liiti1 a1 

SRUN SENDA . 

TYPE A LINE OF TEXTs 26 CHARACTERS OR LESS 
2222222222 

RUN RECVI 

QATA RECEIVED BY “RECVAL"? 

L114 411 

DATA RECEIVED BY "RECVAi"S 


RUN SEND1 
TYPE A LINE OF TEXT» 26 CHARACTERS OR LESS 
cece 


DATA RECEIVED BY "RECV1"S 
33333 
"RECVIi" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 


oe 4-4 A Receiving Task Which Can be Run Before or After 
the Sender (Sheet 3 of 3) 
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Example 4-5 uses Receive Data or Stop in the Receiver and _ Send 
Data followed by Unstop in the sender. These tasks can be run in 
any order. The potential synchronization problems are 
considerably easier to deal with when using this technique of 
synchronization. We will go through it first for running RECV2 
before running SEND2. Then we will discuss the other 
possibilities. The following notes are keyed to the example. 


1) We issue a Receive Data or Stop directive. If there is no 
data packet queued, RECV2 stops and must be unstopped by 
SEND1. If, on the other hand, there is a data packet 
queued, we want to receive it. The DSW equals IS.SET(+2) 
if the task was stopped and then unstopped, and equals 
IS.SUC(+1) if a data packet was received. If RECV2 is run 
first, we stop. 


@ SEND2 gets the data and sends it. We do not need to 
specify an event flag in the Send Data directive since we 
use Stop/Unstop for synchronization. 


@ Unstop RECV2. In this order, this directive will 
successfully unstop RECV2 because RECV2 stopped when it 
issued the Receive Data or Stop directive. 


@ There are two directive errors on UNSTOP which are not 
errors for this set of tasks. Check for these errors and 
if found, asSume that everything worked correctly. If 
RECV2 is active but not stopped, it must be receiving 
another packet. In that case, RECV2 will receive this 
packet on the next Receive Data or Stop directive. If 
RECV2 is not active, it has not been run yet. The packet 
is still in RECV2's receive queue and RECV2 will receive 
it when it is activated. The above situation will not 
oceur the first time through if RECV2 is run first. 


If the error is not one of the two errors’ checked 
for, display an error message and exit. 


@ Check for whether we stopped and unstopped. If so, we 
didn't receive the data packet yet. If not, we did 
receive the data. In this case, if RECV2 is run first, we 
did stop and unstop. 


@ Since we have not yet received the data packet, issue 
another Receive. 


C7 If there is still nothing in the Receive queue, something 
is wrong. Display an error message and exit. 
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rs) After a successful Receive, whether immediately or after 
Stop and Unstop, display the received message. In that 
case, issue another Receive Data or Stop and loop’ through 
again if we have not yet received three messages. If 
there is another data packet queued, we will receive it. 
Otherwise, we stop until SEND2 sends data and unstops us 
again. 


If SEND2 is run once before RECV2, then the Unstop directive at 3 


will fail. If in fact RECV2 is not active at all, or is active 
but not stopped, it will dequeue the data packet when it issues a 
Receive. Hence, we check for these conditions at 4 and just 


exit if either condition caused the Unstop error. When we) run 
RECV2, we do actually receive a data packet at 1. At 5, 
DSW = +1(1IS.SUC) which means that we received a packet and didn't 
stop. Therefore, we display the data and Receive or Stop again. 
This time we will stop until SEND1 unstops us again. 


If SEND2 is run two or three times before RECV2, any data packets 
already sent are received and displayed. In the case of two sent, 
the third RCDS will cause RECV2 to stop until SEND2 sends a_ third 
packet and unstops it. In the case of three packets already sent, 
RECV2 will receive all three and then exit. 


As in Example 4-4, if SEND2 sends more than , three packets, any 


additional packets will be lost because the receive queue is 
flushed when the task exits. 
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FROGRAM SENT2 
C FILE SENDQ2.FTN 


C This task feromets at TI? for a line of text and sends 
CO the date to RECV2 for rrocessing. The receiver will 
> comtinue to rum until it receives 3 messases. 

C Synchronization is handled throush RECV2’s stor bit. 
C RECV2 and SEND2 may be rum in any order. 


C Install and run instructions? RECV2 must be installed. 
BYTE BUFFER (26) ! Send huffer 


INTEGER DSW 
REAL RECV2 


QATA RECV2/5SRRECV2/ ! Receivins task mame 
INTEGER TELTSsTEACT ! Error mnemonics 
MATA TETTSvsIEACT/~89-77 
(° 
TYPE Xs “TYPE A LINE OF TEXTs 26 CHARACTERS OR LESS’ 
2] READ ¢€S95) BUFFER 
3 FORMAT (2681) 


CALL SENDICRECV2+s RUFFERs s0SW) ! Send data to RECV2 
IF (YiSWeEQ.1) GOTO 19 
TYPE X» “UNABLE TO QUEUE DATA TO "RECV2". DSW = ” 
1»DSwW 

10 3) CALL USTFCRECV2s0SW) 
IF (USW.EQ.1) GOTO 20 
IF (QSW.EQ.IEITS) GOTO 


Unstor RECV2 
Branch om directive ok 
! Isn’t he storred? 


! 
! 
20 
G ! 06 6That’s oky he’ll rick 
C !o our data when he 
C: ! executes RCIS# 
ra ) IF (SW.EQ.-IEACT) GOTO 20 ! Is he mot active? If 
C ! oo 6motsy he’1ll Fick ur 
C ! date when activated 


TYFE X»“UNABLE TO UNSTOF “RECV2". [SW = “’sDSW 
! Any other error is had 
20 CALL EXIT ! Exit 
END 


Example 4-5 Synchronizing a Receiving Task Using RCDS 
(Sheet 1 of 3) 
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FROGRAM RECV2 
FILE RECV2,.FTN-: 
. It ferints the 


7 it waits 
2 tid 


datas 


This task synchronizes with its 
” Because of this 
im any orders with any relative 


Install and run instructions? 


INTEGER RBUFF CIS) ! 
INTEGER USWsTSSET 
DATA ISSET/2/ | 


YO 100» T=1s3 : 
CALL RCOSTCsR BUFF » DSW) ! 
IF (0SW.GE.0> GOTO So 
Tyre K»y’RECEIVE DIRECTIVE 
1 0SW = “nsw ! 
GOTO 1000 | 
C° 
> Successful receirt or 
CG check 
we hav 


unstorred 

for unstorred after heing 
to receive the data 

IF (SW.NE.ISSET) GOTO 60 


rs] 
(C 


C Storred due to mo datas 


CALL RECEIV(»RBUFF » » DSW) 
IF (LSW.EQ.1) GOTO 60 
TYPE *» “RECEIVE DIRECTIVE 

@ jiunstorren. usw = “ynsw 
GOTO 1000 

CO Uisrelay data 


eee 


40 TYFE 75» C(RBUFF (J) »J=3915) 
73 FORMAT ¢° DATA RECEIVED 
LOO CONTINUE 


C Have received 3 messases 


TYPE xX» ’*"RECV2" 


1 NOW EXIT’ 
1000 CALL EXIT ! 
ENTII 


Example 4-5 
(Sheet 2 of 
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syunchronizatiorsy 


RECV2 


RY 


HAS RECEIVED 


COMMUNICATION 


This task receives data from another task (e.g. SENT2), 
glons with @ header» 
for another data rackets 
it has received 3 messages. 


on TI. Then 


continuing this 


sender usims RCST. 
the tasks can be run 
eriorities. 


must be installed, 


Receive buffer 


NSW code mnemonic 


Receive from anyone 


FAILED IN "RECV2",. 
llisslay error mesgase 
and exit 


by another task. First 
storredsy im which case 


! Were we storred due 
! to mo data? If not 
! (NE) » we have 2 

! data racket 

! Now set the racket 
FATLED AFTER "RECV2* 


! Tliselay error 
! MEeSseste and exit 


"RECV2"3°/1X»v13A2) 


3 MESSAGES AND WILL 


xit 


Synchronizing a Receiving Task Using RCDS 
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Rum Session 


! Rum RECVS firsts then rum SENI2 3 times 
SINS RECYV2 

SRUN RECV2 

>ZRUN SENDT2 

TYFE A LINE OF TEXT» 26 CHARACTERS OR LESS 
LULLAL1 11 

IATA RECEIVED BY "“RECV2"3 


CEEEECEE! 
“RUN SEND 
TYPE A LINE OF TEXT» 26 CHARACTERS OR LESS 


oF att at, at 


Ave Bae Wee Ree Bie 


SRUN SEND2 

TYPE A LINE OF TEXTy 26 CHARACTERS OR LESS 
3333333333333333333333333 

NATA RECEIVED BY "RECV2"3 


" 3333333333333333333333333 
"RECV2" HAS RECEIVED 3 MESSAGES AND WILL NOW EXIT 


! Run SEND? once firsts then rum RECV2s and then rum SEND2 twice more 
>RUN SENTI2 

TYFE A LINE OF TEXTs 26 CHARACTERS OR LESS 

44444 

“RUN RECV2 


QATA RECEIVED BY "RECV2"? 
A4A4G 
>RUN SEND2 
TYFE A LINE OF TEXT» 26 CHARACTERS OR LESS 


Nite keke kw kw ke be) 


DATA RECETVED BY "RECV2"3 
bes be be bw bw be 

>RUN SENTD2 
TYFE A LINE OF TEXT» 26 CHARACTERS OR LESS 
66 

DATA RECEIVED BY "RECV2"3 


OG 
"RECV2" HAS RECEIVED 3 MESSAGES ANT WILL NOW EXIT 


Example 4-5 Synchronizing a Receiving Task Using RCDS 
(Sheet 3 of 3). 
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Using Send/Receive Directives for Synchronization 


If it is desirable to pass data as well as notify another task of 
the occurrence of an event, the Send/Receive directives can be 
used to perform this double function. The advantage of this 
approach is that data can be sent in addition to notifying the 
other task of the occurrence of the event. The receiving task can 
synchronize with the event using any of the techniques listed in 
Table 4-5. 


Slaving the Receiving Task 


Normally, a task runs under the UIC and the TI: of its initiator, 
the operator issuing the RUN command, or the task issuing the 
Request Task directive (REQUES). A receiver task which is-~ run 
from the same terminal as the sender is assigned the same UIC and 
TI: as the sender. However, if the receiver is run from another 
terminal or by a different user, it's UIC and/or TI: may be 
different from that of the sender. Also, a receiver might receive 
data from several different tasks initiated at several different 
terminals. 


If it is desirable to have the receiver task take on the UIC and 
the TI: of the sender each time data is received, the receiver 
task can be built as a slaved task. The advantages of this: 
approach are that the receiver then acquires the same privileges 
as the sending task and can also do I/O directly to the _ sending 
task's terminal (through TI:). To build a task as a slaved task, 
either task-build with the /SLAVE qualifier or install with the 
/SLAVE qualifier. 
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PARENT /OFFSPRING TASKING 


In multitasking situations, it is often useful to have one task 
activate and monitor other tasks, or monitor already active tasks. 
In particular, the requesting task may wish to receive periodic 
Status reports from the other tasks during execution, or when the 
tasks exit. 3 


For example, a task to secure a nuclear reactor in case of 
accident activates a pair of subordinate tasks, one task to issue 
warnings to personnel and the other to initiate the shutdown 
procedure. The task which activates the two subordinate tasks can 
receive periodic status reports from each of the other tasks, _ So 
that it can take appropriate action in case of a problem. In 
particular, it would want to know about any failure in either 
operation. 


Under RSX-11M, parent/offspring tasking provides a facility for 
setting tasks up in the structure described above. As we shall 
see, this is easier to program than Send/Receive directives. A 
parent task is one which connects’ to or spawns another task, 
called an offspring task. 


When a task spawns another task, it both activates the task and 
establishes a connection to it. If the task is already active, a 
parent task should just connect to the offspring. Figure 4-1 
shows this relationship. When a task spawns another task it can 
also send a command line or data of up to 79 characters (or bytes) 
to the offspring. 


Once the connection is established using Spawn or Connect, the 
offspring can send or emit status by using the Emit Status (EMST) 
directive. This allows the offspring to send a one-word status 
value to the parent. Upon exit, a success code (EXSSUC=+1) ‘is 
returned if the standard EXIT is used, or a specified one-word 
status can be returned if the Exit With Status directive (EXST) is 
used. If the task is aborted, a standard severe warning code 
(EXSSEV=+4) is returned. The status is automatically returned in 
a status block in the parent task -- no receive directive is 
needed. Synchronization can be handled using event flags or an 
AST routine. The flag is set or the AST routine entered when’ the 
status is received. Table 4-6 shows the standard status codes. 
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PARENT 


SPAWN OFFSPRING COMMAND LINE 


OFFSPRING 


EXIT, EXIT 
WITH STATUS, 
EVENT FLAG AND/OR OR EMIT 


AST ROUTINE OFFSPRING STATUS STATUS 


TK-7745 


Figure 4-1 Parent/Offspring Communication Facilities 
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Additional directives are provided for parent/offspring support. 
The Send Data, Request, and Connect directive combines’ the 
functions of the three separate directives (Send, Request, and 
Connect) into a single directive. This is similar to Spawn, but 
sends a 13 word data packet rather than a 79 byte command line. 
It also just sends data and connects if the task is already 
active. Spawn is rejected if the task is already active, unless 
the task is a CLI (Command Line Interpreter). 


Two other directives are provided to allow chaining, or passing a 


parent/offspring connection from an offspring to another task. We 
will discuss chaining in more detail later in this module. 


Table 4-6 Standard Exit Status Codes 


Mnemonic Value Meaning 

EXSWAR i) Warning -- task succeeded, but 
irregularities are possible 

EXSSUC 1 Success -~- results as expected 

EXSERR 2 Error -- results unlikely to be 
as expected 

EXSSEV 4 Severe Error -- one or more fatal 

errors were detected, or offspring 
aborted. 


The above symbols could be used in a FORTRAN program by dropping 


the $ sign from the symbol and using them as a variable name with 
the appropriate values. 
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Directives Issued by a Parent Task 


Table 4-7 summarizes the directives which may be issued by a 
parent task. Note that parent and offspring are relative terms, 
an offspring of one task may be the parent of another. 


Table 4-7 Comparison of Parent Directives 


Send, Request 
Characteristic Spawn Connect and Connect 


Can be used for Yes No Yes 
offspring which 
is not yet active 


Can be used with No, except Yes Yes 
offspring which if offspring 
is already active is a Command 


Line Inter- 
preter (CLI) 


Can pass data (or Yes (up to. No Yes (13 words) 
command) to off- 79 bytes) 

spring as part 

of directive* 


Can be used to Yes No No 
pass commands to 

a Command Line 

Interpreter (CLI) 


* If a parent/offspring relationship is established via Connect, 
the tasks can of course exchange data using Send/Receive. The 
table above indicates whether the passing of data from parent 
to offspring is a capability of the directive in and of itself. 
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LEARNING ACTIVITY 


Chapter 4 of the RSX-11M/M-PLUS Executive 
Reference Manual contains a good discussion 
of the Parent/Offspring directives and in 
particular it gives a number of possible uses 
for them. We will not discuss these various 
uses anywhere in this course. 


Read Sections 4.1, 4.2, and 4.3 of the 
RSX-11M/M-PLUS Executive Reference Manual for 
a discussion of the Parent/Offspring 


directives and examples of their use in 
applications. 
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Table 4-8 summarizes the arguments for the Spawn directive, the 
Connect directive, and the Send Data, Request, and Connect 
directive. For additional information, see the writeup on each 
directive in Chapter 5 of the RSX-11M/M~PLUS Executive Reference 
Manual. ; 


Table 4-8 Directives Used by a Task to 
Establish a Parent/Offspring Relationship 


Directive Directive 

Name Call . 

Spawn CALL SPAWN(tsk,grp,mem,efn,ast,esb,param, 
cmdlin,cmdlen,unum,dnam,dsw) 

Connect CALL CNCT(tsk,efn,ast,esb,param,dsw) 

Send, CALL SDRC(tsk,buf,efn,ast,esb,param,dsw) 

Request, 


and Connect 
tsk - offspring task 
grp,mem ~ UIC offspring will run under 


efn - event flag to be set when offspring exits or emits 
status 


ast - AST routine to be entered when offspring exits or 
emits status. 


esb - exit status block address 


param ~ name of a word to receive the status block address 
when the AST. occurs 


cmdlin,cmdlen - address of buffer with command line, 
length of command line 


unum,dnam - device to be TI: for offspring 
buf - 13(18) word buffer to be sent 


dsw - directive status word 
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4-6 shows a task which spawns PIP to display a directory 
The following notes are keyed to the example. 


The command line to be passed to PIP. We include the 
three character command name to be consistent with the way 
MCR passes commands if a utility command is typed to MCR. 


Display startup message. 


Spawn ...PIP. Event flag 1 will be set when ...PIP exits 
or emits status. EXSTAT is the address of the eight-word 
status block (only the first word is used). CMD is’ the 
starting address of the command line and _ LEN is its 
length. 


Wait for event flag 1 to be set when ...PIP exits or emits 
status. Notice that this is a local event flag, local to 
this task, which is cleared by the Executive when the task 
is spawned and set by the Executive when the spawned task 
exits or emits status. 


The high-order byte of the exit status code may contain 
unexpected data. Therefore, clear that byte by specifying 
the logical AND of the code and 377(8) before displaying 
the code. 


On the Run Session - The first run session shows a 
successful exit by ...PIP, the second one shows ...PIP 
aborted by an operator. Note the different status codes. 


NOTE 

On an RSX-11M system, an attempt to spawn 
e+ePIP will fail if ...PIP is already active. 
This works diffently from initiating PIP from 
MCR, where an attempt is made to install the 
task ...PIP under the name PIPTnn if ...PIP 
is already active. A solution to this 
problem is to spawn CLI... (the current 
CLI), .-e-DCL (DCL) or MCR... (MCR) and send 
it the command line. It will in turn = start 
up the appropriate PIP task under ...PIP or 
PIPTnn, as if the command was typed in by an 
operator. See section 4.4 (on Spawning 
System Tasks) of the RSX-l11M/M-PLUS Executive 
Reference Manual for additional information. 
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FROGRKAM SFWN 


C File SPAWN.FTN 


C This Frosram seawnis FIP» rasses it & command Line to 
CO disrelay a directory at Tlisy waits for it to exits and 


C Yate 


et 
ade 

: 3] 

3B 


CG Error 
900 


PLO 
1000 


Example 


then diselavys its exit status. 


INTEGER EXSTAT (8) sPLIST( 3) »uSW 
BYTE BUFF (80) 

REAL PIP» CMC 3) 

DATA FIP/6R.+ ¢FIFS 

DATA CMDI//RIF “9 ’R.MAS y “C/LICS 


WRITE (S915) ! Write messade 
FORMAT ¢° SFAWN IS STARTING ANI WILL SFAWN FIF?’) 
CALL SPAWNCFIFP ys yl» sEXSTATs sCMDy 12s » TSW) 
, ! Srawn FIP 

IF (Sw.h7T.0) GOTO 900 ! Branch on dir error 
CALL WAITFR(1+s0SW) ! Wait for task to exit 
TF (YSW.LT.O) GOTO 910 ! Branch on dir error 
WRITE (S925) EXSTATC1).ANDT.°377 ! Diselay low 

! byte of exit status 
FORMAT ¢€’ SFAWN REFORTING? FIP EXITED: EXIT 
ISTATUS WAS ’»T1s’.%) 
CALL EXIT 1 Exit 
handlins code 
TYPE Xs’ERROR SPAWNING FIF. [NSW = %»0SW 
GOTO 1000 
TYPE *»y “ERROR WAITING FOR EVENT FLAG. DSW = “’»tSW 
CALL EXIT 
END 


4-6 A Task Which Spawns PIP (Sheet 1 of 2) 
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Run Session 


RUN SFAWN 


USING DIRECTIVES FOR INTERTASK COMMUNICATION 


SPAWN 


IS STARTING ANI 


We MACS 1 1. 
AL.MACS2 1. 
A+MACS 1 1. 
SPAWN .MAC $22 le 


Total 127./129. blocks in 
” SPAWN REPORTING? FIF EXITED, 


“=RUN SPAWN 
SFAWN IS STARTING AND WILL SPAWN FIF 


WeMACS 1 Le 
AL-MAC#2 1. 
AsMACS 1 1. 
NCLZABRORT/TASK ..+PIF 
AP .MACS 12 4. 
12315215 Task “...PIF" 


WILL SFAWN FIF 


Directory DBIS C305» 3019 
B8-MAR-82 12315 


20~-MAY~81 


O9-TEC~8O 
10-JUN-81 


08-SEP-81 


mide 


files 


Nirectory DBISC 3053017 
8-MAR-82 127315 


20-MAY~81 
09-TEC-80 
10-JUN-S1 


2il-MAY~81 


terminated 


13304 
16358 


15321 


EXIT STATUS WAS i. 


13204— 
16258 


15321 


13350 


Aborted via directive or CLI 
And with vrendinse IT/0 reauests 


Example 4-6 A Task Which Spawns PIP 
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USING DIRECTIVES FOR INTERTASK COMMUNICATION 


Example 4-7 is a more generalized spawning task, which prompts for 
the name of a task and a command line and then spawns that task, 
sending the input command line to it. The following notes are 
keyed to the example. 


Prompt for and get the task name. The task name must be 
entered in all uppercase characters. To allow lowercase 
characters, the code must be modified to check for any 
lowercase characters and convert them to uppercase. 


Convert ASCII task name to Radix-5@ format. 
Prompt for and get command line. 


Spawn task specified. We are using event flag 1 for 
synchronization. The status will be returned in EXSTAT. 


Wait for event flag 1 to be set, indicating that the task 
has exited (or emitted status). 


Clear high-order byte of the status word and display it. 
Note that CLI... passes the command line to the current 
CLI (DCL) which in turn invokes task DIRT11 to display the 
directory. (This is task DIR spawned at terminal T11) 
BUFFER(1) and (2) are set to blanks in case a name of less 


than six characters is entered. By clearing to blanks, a 
short name is assured of having trailing blanks. 
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FROGRAM GSFAWN 


C FILE GSFAWN.FTN 


C This task eromets at tit for @ task name and command 


CO Lines then srawns the srecified task end ra 
C conmand Line. After that it waits until the 
CG task exits and diselays its exit status. 


ses it the 
off srring 


CGC Run instructions? The mame of the task to be srawned 


REAL BUFFERC 20) » TSKNAM 
INTEGER EXSTAT(8) 

C Fad task mame buffer with blanks in case ma 
VATA BUFFERCL)»yRUFFERC2) 7° vy? 


WRITE (S915) 

LS 1) FORMAT ¢€’ TASK NAME?’ > 

REAQ (3225) BUFFERC1)»BUFFER(2> 

wo FORMAT ¢2A4) 

C Convert task mame to Radix-50 format 
CALL IRADSO (4»BUFFER» TSKNAM) 
WRITE (S35) 


35 FORMAT (’ COMMANID LINE (79 CHARACTERS 
© [rear (5.45) Ny BUFFER 
45 FORMAT (Q*20A4) 


C Seawn task with command line 
CALL SPAWN CTSKNAMs ysis sEXSTATs »sRUFFE 
IF €iI0SW .LT. 0) GOTO 900 ! Branch on 
C Wait for task to exit 
CALL WAITFR Cis TOSW) 
IF ¢CI0SW LT. 0) GOTO 910 ! Branch on 
WRITE (S955) EXSTATC1) AND. °377 
a Be) 6 FORMAT ¢€70%%10X»’TASK EXITED. STATUS 


1/3) 
GOTO 1000 ! Go to com 
C Error code 
700 WRITE (S905) Tosw 
905 FORMAT ¢€¢% DIRECTIVE ERROR SFAWNING TA 
1yI4) 
GOTO 1000 
910 WRITE (Ss915) INSW : 
915 FORMAT ¢° DIRECTIVE ERROR ON WATT FOR 
114) 
1.000 CALL EXIT 
EN 


Example 4-7 A Generalized Spawning Task 
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7 must be tered im using Bll urrer case characters. 


me is short 
/ 


OR LESS?’ > 


RyNv oe TTISW) 
dir error 


dir error 


WAS ‘vsI2e’.’ 


mom exit 


SK. DSW = ” 


+ DSW = %y 


(Sheet 1 of 
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Run Session 


“RUN GSFAWN 

TASK NAME? 

ee o PIF 

COMMAND LINE (€79 CHARACTERS OR LESS)? 
PIF &eNIS/LI 


Nireetory YRLSC305»301 9 
88-SEP-81 15209 


FRIENDS .0IS$¢2 Ls LO-AUG-81 11°13 
FRIENDSNL.UIS #2 1. S1-AUG-81 11:42 


Total of 24/10. blocks in 2. files 


TASK EXITED. STATUS WAS 1. 


“RUN GSFAWN 

TASK NAME? 

ee TCL 

COMMAND LINE ¢€79 CHARACTERS OR LESS 2? 
QIRECTORY *.MAC 


Directory DBISC 30523017 
8-SEP-B1l 15310 


WeMACS1 1. : 2O0-MAY-81 13204 
AL.MACS2 1. O9-DEC-80 16358 
AeMACS 1 1. LO-JUN-81 15321 
AY.MAC12 4, 21-MAY-81 13350 
FORMAT .MAC§ 34 be 21-AUG-81 11253 
FROGGY «MACE 1 1. 30-JAN-81 14327 
FROGZ+MACS 1 1. 30~JAN-81 14230 
RAY «MACS 1 4, 3O-JAN-81 14339 
FROGX +«MACHS 1. 5O~JAN~-81 14342 
C.MACSS 1. 2l-MAY-81 10301 
AZ.MACE2 1. 21-MAY-81 102304 
C2.MACH1 21-MAY-S81 10304 


1s 
Task "IRTII" terminated 
7 | Aborted vie directive or CLI 
And with rendins I/0 reauests 


TASK EXITED. STATUS WAS 4. 


Example 4-7 A Generalized Spawning Task (Sheet 2 of 2) 
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Directives Issued by an Offspring Task 


Table 4-9 summarizes the directives which can be used by an 
‘offspring to return status to a parent task. Table 4-6 shows the 
standard exit status codes used on the system. An offspring can 
also spawn or connect to other tasks as well. 


Table 4-9 Directives Which Return Status 
to a Parent Task 


Directive Effect/Use 


CALL EXIT Exits and returns "Success" status 
to all current parent tasks. 


Special case of CALL EXST 


CALL EXST(status) Exits and returns specified one- 
word status to all current parent 
tasks. 


Terminates parent/offspring 


relationship. 
CALL EMST Emit specified status to specified 
(parent-task,status,dsw) parent (or to all parents, if 


parent task name is omitted). 


Terminates the parent/offspring 
relationship. The connection can 
be reestablished by the parent, 
using the Connect Directive. 


NOTE 
The Executive returns "Severe Exit" status if 
the task is aborted or if a fatal error 
occurs. 
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Chaining of Parent/Offspring Relationships 


An offspring can chain or pass its parent/offspring connection on 
to another task. In that case the connection between the parent 
and the offspring which passes the connection is broken. In its 


place, a connection is made between the parent and the new 
offspring. 


Figure 4-2 shows the difference between an offspring spawning 
another task versus chaining its connection to another task. Note 
that with spawn, the connection between the parent and the _ first 
offspring still exists, plus a new connection is established 
between the first offspring and the new offspring. 


Table 4-18 summarizes the directives which can be used to chain 
parent/offspring relationships. Request and Pass Offspring 
Information (RPOI) is similar to Spawn in function, in that it 
starts up the task and can pass a 79 byte command line. Send 
Data, Request, and Pass Offspring Control Block (SDRP) is similar 
to Send Data, Request and Connect, in that it sends a 13 word data 
packet and it succeeds even if the task is already active. 
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TASK 2 TASK 2 REQUESTS 
SPAWNS AND PASSES OFFSPRING 
TASK 3 INFORMATION 
BEFORE AFTER BEFORE AFTER 
TASK 1 TASK 1 


| 
| 
| 
| 
TASK 2 | 
| 
| 
| 


| 
| 
| 
| 
Task 2 | | 
| 
| 
| 
| 
| 


NOTE: EACH ARROW SHOWS A PARENT/OFFSPRING CONNECTION. 
THE ARROW STARTS AT THE PARENT AND POINTS TO THE OFFSPRING. 


TK-7746 


Figure 4-2 Spawning Versus Chaining 
(Request and Pass Offspring Information) 
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Table 4-19 Directives Which Pass Parent/Offspring 
Connections to Other Tasks 


Characteristic 


Can be used for a 
new offspring which 
is not yet active 


Can be used for a 
new offspring which 
is already active 


Can pass data (or a 
command) to a new 
offspring 


Can be used to pass 
commands to a CLI 


RPOI SDRP 

Yes Yes 

No, unless Yes 

the offspring 

is CLI 

Yes (up to Yes (13 words) 
79 bytes) . 

Yes - No 
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Example 4-8 shows the use of the Request and Pass Offspring 
Information (RPOI) directive. This task is similar to example 
4-6, but it uses RPOI instead of SPAWN. Two run sessions”) are 
provided, showing the difference between an offspring passing its 
parent/task connection = and an offspring spawning another 
offspring. In the first run session, GSPAWN spawns’ PASSIT 
(Example 4-8), which starts up PIP, passing its connection 
(GSPAWN/PASSIT) on to. PIP. In the second run session, GSPAWN 
spawns SPAWN (Example 4-6), which spawns PIP. Note that with 
PASSIT, ...PIP returns its exit status directly to GSPAWN. GSPAWN 
is no longer connected to PASSIT once the connection is passed on 
to PIP. With SPAWN, ...PIP returns its exit status to SPAWN. 
SPAWN displays that status and then exits, sending its own exit 
status to GSPAWN. © 


The following notes are keyed to the example. 


@ Use RPOI instead of SPAWN. No event flag is needed nor is 
a status block set up since this task won't receive status 
from ...PIP. The seventh argument in the argument list 
(MACRO symbolic name RP.OAL, suggested FORTRAN name RPOAL) 
determines what parent (fixed) connections are passed, if 
any. If RPOAL has a value of 1, as in the example, all 
connections are passed. (In this example there is only 
one connection.) A connection is established between the 
parent of PASSIT (GSPAWN) and ...PIP. The connection 
between GSPAWN and PASSIT is broken. 


2] Display a message and exit with a status of 1@., to make 
it easy to tell whether the status is from this task or 
from ...PIP. Note in SPAWN that the CALL EXIT is’ used, 
which results in a Success Code (+1) being sent as the 
exit status. 


@ 0n the First Run Session (GSPAWN spawns PASSIT) - The exit 
status from ...PIP is returned directly to GSPAWN. 


@ on the Second Run Session (GSPAWN spawns SPAWN) - The exit 
Status from ...PIP is returned to SPAWN, then SPAWN 
returns its own exit status to GSPAWN. 


If you wish to chain the connection from only one of several 
parents, specify a single task, and do not specify RPOAL in the 
RPOI directive call. 


If RPOAL is not specified and no task is specified, then no 


connections are _ passed. This might be useful to request a task 
and send 79 bytes of data when a connection is not needed. 
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N 


FROGRAM FASSIT 
C File FASSIT.FTN 


C This rrogram reauests PIF» rasses it a command line to 
> Giselay @ directory at Tilis and rasses it all of its 
> Farent conmmections as well 


C Nate 
INTEGER FLISTC(3) »0SW 
BYTE BUFF C80) 
REAL FIF yy CMDOC 3) 
DATA FPIF/6R..+FPIFZ 
DATA CMDI//RIF ¢’9 “K.MA’ » “C/LICS 


WRITE (S915) ! Write message 
15 FORMAT ¢’ FASSIT IS STARTING AND WILL REQUEST FIF’) 
@ CALL RPOI (PIP sss» CMDiyl2vivyye20SW) ! Reavest FIF 
IF (OSW.LT.O> GOTO 900 ! Branch om dir error 


WRITE (3223) ! Write message 
20 (2 FORMAT ¢° FPASSIT REQUESTED PIF AND WILL NOW EXIT’) 
CALL. EXST ¢€10) ! Exit with status of 10 
(C-Error handling code 
700 TYPE X»y’ERROR REQUESTING FIF. [SW = “»tSW 
CALL EXIT 
ENIt 


Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 1 of 3) 
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Run Session 


“INS FASSIT 

“RUN GSFAWN 

TASK NAME? 

PASSIT 

COMMAND LINE ¢79 CHARACTERS OR LESS)? 


PFASSIT IS STARTING AND WILL REQUEST PIF 
FASSIT HAS REQUESTED PIF AND WILL NOW EXIT 


Directory DEL{L305»301] 
Q-MAR-82 15222 


WeMACS 1 1. 20-MAY-81 13:04 
ALsMACSs2 1. O9-DNEC-80 16:58 


SPAWN.+MAC$1 4, O8-SEFP-81 13:32 


Total of 13.766. blocks im 15. files 


© TASk EXITED. STATUS WAS 1. 


RUN GSFAWN 

TASK NAME? 

PASSIT 

COMMAND LINE (79 CHARACTERS OR LESS)? 


FASSIT IS STARTING AND WILL REQUEST PIF 
PASSIT HAS REQUESTED FIF AND WILL NOW EXIT 


Yirectory DRLIL3S0S%s3017 
8-SEF-81 15223 


WeMACS 1 1. 20~-MAY-81 13204 
AL.MACS2 1. O9-TEC~80 162358 
AeMACS1 1. 10-JUN-81 15¢e21 
AY.MACS12 4. 21-MAY-81 13350 


15324310 Task "...+FPIF" terminated 
Aborted via directive or CLI 
And with rending I/0 reauests 


© task EXxITEN, sTaTUS WAS 4. 


Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 2 of 3) 
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Kun Session 


SINS SPAWN 
“RUN GSPFAWN 
TASK NAME? 
SPAWN 
COMMAND LINE 


(79 CHARACTERS OR LESS)? 


SPAWN IS STARTING ANI! WILL SPAWN PIF 


Yirectory DRLIC3OSs 3011 
B-MAR-B2 15122 


WeMACS I = 20—MAY~81 
AL MACH? be 09-LEC~80 
SPAWN. MACE Ae 08-SEF~81 
Total of 13./66. blocks in 15. files 

SPAWN REPORTING? PIP EXITED, EXIT STATUS 


4 TASK EXITED. STATUS WAS 1. 


RUN GSFAWN 

TASK NAME? 

SPAWN | 

COMMANID LINE (79 CHARACTERS OR LESS)? 


SPAWN IS STARTING AND WILL SPAWN FIF 


° [ 


Virectory NBLICSOS»3007 


§-SEP<B1 15323 


2O0-MAY~-81 


WeMAC HI le 

Ail «MACS 2 le 09-NEC-80 
AMACE1 1s 10~-JUN~81 
NCLZ>ABORT/TASK «++FIF 

APsMACK12 4. 21-MAY-81 
L5324310 Task ".+sPIF" terminated 


Aborted via directive or CLI 
And with eendins I/0 reauests 
SPAWN REPORTING? FIF EXITED» EXIT STATUS 


TASK EXITED. STATUS WAS 1. 


13304 
16358 


13332 


WAS 1. 


13204 
16358 


1S321 


13350 


WAS 4. 


Example 4-8 An Offspring Task Which Chains Its 
Parent/Offspring Connection to PIP (Sheet 3 of 3) 
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Other Parent/Offspring Considerations 


Retrieving Command Lines in Spawned Tasks - Use the Get MCR 
Command Line directive (GETMCR). The passed command is returned 
to a buffer specified in the GETMCR call. 


Spawning a Utility or Other MCR Spawnable Task - Utilities are 
generally installed under task names of the form ...tsk. This 
makes them MCR spawnable tasks, which notifies MCR to _ spawn 
multiple copies of the task under names tskTnn if the task is 
invoked as an MCR command uSing the three-character task name 
(e.g., PIP /LI). In fact, any task is spawnable, but only tasks 
installed under a name of this form are spawned as multiple copy 
tasks by MCR. When such a task is invoked by MCR, MCR passes it 
the entire command line, including the three-character task name 
(e.g., PIP /LI). Even if you spawn a utility directly, you should 
pass a command line which includes the three-character task name. 
This maintains compatibility with the format. used by MCR to pass 
commands to utilities, and avoids potential problems caused when 
the utility parses your command line. 


On RSX-11M systems, there is more likelihood of getting a task 
already active failure if you spawn a utility directly using the 
name ...tsk than there is if you instead spawn MCR... and pass 
the command line which includes the task name. This is due to the 
fact that if a task is spawned directly using ...tsk, the spawn 
attempt fails if the task ...tsk is aready active. No attempt is 
made to install the task under the name tskTnn if ...tsk is 
already active, as is the case if you spawn MCR... (MCR) to start 
up the utility. 
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Example 4-9 showsS a spawned task which retrieves a simple command 
line of the form SPW n, where n is a single character. If n=l, 
SPW performs a simple addition exercise and displays the answer. 
If n=2, SPW performs a simple multiplication exercise instead. 
Else, SPW displays the message "NO OTHER OPERATIONS ALLOWED". 
This task, like most system utilities, will run correctly whether 
spawned directly by a task (as ...SPW), started by MCR as_ the 
result of a command line sent when spawning MCR, or invoked by an 
operator using an MCR command. 


The following notes are keyed to Example 4-9. 

@ CALL GETMCR to get the command line. 

@ Display the command line as received. . 

@ Check the value of n for an ASCII 1, skipping over the 
characters SPW and _ the blank after SPW. Note that in a 
real application, the first part of the command line 
should be checked as well to see that it really is SPW and 
a blank. Branch if not equal. 

Check n for an ASCII 2. If not branch to error at 7. 
If n=l, perform a simple addition (2+5). 


If n=2, perform a simple multiplication (2x5). 


If n is neither al nor a 2, display an error message and 
exit with warning status(Q@). 


If n was 1 or 2, display a message giving the results of 
the computation and then exit with success status (+1). 


This run session shows ...SPW being spawned three times by 
MCR, when an operator types an MCR command line. 


e008 886808 


This run session shows ...SPW being invoked three times by 
running GSPAWN, which in turn spawns ...SPW. 
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FROGRAM SPWNET 
File SFWNED.FTN 


This task uses the GETMCR directive 
line from either TI! or the erarent t 
echoes the command line and does an 
tures out the answer -and emits statu 


Task~-build instructions? 


=LINK/SMAF 
/~>LIBRARY 


Install and run instructions? To mak 
srawnables install it under the name 
lines should be of the form SFW fune 
functions are 1 and 2. 


OGIO AAIAS OH 


‘BYTE INBUFF C80) 
INTEGER TOSBC(2) »0SwW 


INTEGER NUM1 »NUM2sANS 
VATA NUMLsNUM2/5 92/7 
BYTE OF 
C 
1) CALL GETMCRCINBUFF » TSW? ! 
IF (uSW.GT.O>) GOTO 10 
TYPE x» ’OTUN’’T GET COMMAND LI 
10 TYPE 25 CINBUFF CT) »yT=1»0SW) ! 
C ! 
15 FORMAT (1iX»s80A1) 
C Check for function ils branch if mot 
IF CINBUFFC(S).NE.’°1°) GOTO 20 
Gans = NUM1 + NUM2 ! 
OF = 7+? ! 
GOTO 30 | 
! 
C Check for funetion 2» branch if mot 
20 IF CINBUFFC(S).NE.’°2°) GOTO 40 
ANS = NUML * NUM2 ! 
OF = ‘x? 
30 TYPE 35»NUM1»O0F »>NUM2sANS ! 
35 rs) FORMAT (iX»T1iviXvAlsTI29’ =’ 912 
CALL EXSTC(1) i 
Cc ! 
C QLisrelay no of messase 
40 TYPE x»’ NO OTHER OPERATIONS A 
@ [cart exstco) ! 
C ! 


END 


to get & command 
ask. It then 

add or multirlyy 
$ on exit 


SFWNETy LBs CL» LIPROGSUBS/LIBRARY »FOROTS— 


e this task MCR 
7+ ¢SFW. Command 
tion ~- valid 


Get command line 


eee 
ee 


NE. DSW ‘TSW 
Yisrelay the 


command line 


lo addition 

Set oreration sign 

Vigserlay results 
and exit 


lo multirlication 

Set oreration sism 

Ttiselay results 
fe? 

g9’.%) 

Exit with success 
status 


LIOWET ¢ 
Exit with warning 
status 


Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 1 of 2) 
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Run Session 


SINS/TASK.NAME?...SFPW SFWNET 
SMCR SPW 1 

SPW od 

9 +t 2 = 7, 

>MCR SFW 2 

SPW 2 

ov * 2 = 10, 

“MCR SPW 3 

SPW 3 

NO OTHER OPERATIONS ALLOWED 


“RUN GSPAWN 

TASK NAME? 

0+ + SPW 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW 1 

SPW 1 


2 ¢2 = 7, 


TASK EXITED. STATUS WAS 1. 
“RUN GSPAUN 

TASK NAME? 

oe SFU 

COMMAND LINE (79 CHARACTERS OR LESS)? 
SPW 2 
SFU 2 


3k 2 = 10. 


3 


TASK EXITED. STATUS WAS 1. 


RUN GSPAWN 

TASK NAME? 

++ + SPW 

COMMAND LINE ¢€79 CHARACTERS OR LESS)? 
SPW 3 . 

SPW 3 


NO OTHER OPERATIONS ALLOWED 


TASK EXITED. STATUS WAS O. 


Example 4-9 A Spawned Task Which Retrieves a 
Command Line (Sheet 2 of 2) 
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Task Abort Status - When establishing a parent/offspring 
connection, it is possible to request a second word of status when 
a task exits. In that case, the second word of the status’ block 
returns the task abort status. This word allows a parent task to 
distinguish the different reasons for return of "Severe Error" 
status. 


Table 4-11 lists the various task abort status codes. To get’ the 
second status word, place any nonzero value in the high byte of 


the event flag argument word. To do this, specify the logical OR 
of 256 and the event flag number. 


Example: 


CALL SPAWN (TASKS,,,,,256.OR.12, ,STAT,CMD, LCMD) 


Table 4-11 Task Abort Status Codes 
Exit 

Mnemonic Value Status Meaning 
S.CEXT -2(19) EXS$SUC=1 Task exited normally 
S.COAD @ EXSSEV=4 Odd address and traps to 4 
S.CSGF 2(18) EXSSEV Segment fault 
S.CBPT 4 (10) EXSSEV Break point or trace trap 
S.CIOT 6 (198) EXSSEV IOT instruction 
S.CILI 8 (18) EXSSEV Illegal or reserved instruction 
S.CEMT 18(18) EXSSEV Non RSX EMT instruction 
S.CTRP 12(18) EXSSEV Trap instruction 
S.CFLT 14(1@) EXSSEV 11/4@ floating-point exception 
S.CSST 16(18)  EXSSEV SST abort - bad stack 
S.CAST 18 (19) EXSSEV AST abort - bad stack 
S.CABO 28 (18) EXSSEV Abort via directive or CLI command 
S.CLRF 22 (18) EXSSEV Task load request failure 
S.CCRF 24(18) EXSSEV Task checkpoint read failure 
S.IOMG 26 (10) EXSSEV Task exit with outstanding I/O 
S.PRTY 28 (18) EXSSEV Task memory parity error 
S.CPMD 38(18) EXSSEV Task aborted with PMD request 
S.CINS 32 (18) EXSSEV Task installed in two different 


systems 
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Summary of Various Methods of Data Transfer Between Tasks 


Table 4-12 summarizes and compares the 


various 


methods of 


transfer between tasks which we have discussed so far. 


Comparison of Methods of Data Transfer 


Method 


Send/ 
Receive 


Spawn 
Command 
Line 


Off- 
spring 
Status 


. returns status 


Table 4-12 Comparison of Methods 


Maximum 
Amount 


13(19) 
words 


79(18) 
bytes 


l or 2 
words 


Transfer Between Tasks 


Direction/ 
Repetition 


Pool 


Restrictions Requirements 


None 


Parent to 
offspring 
only 


Offspring 


must exit 
for parent 
to pass 
another 
command 


Offspring 
to parent 
only 


Parent must 


reconnect to 
offspring to 


Data packet 
is buffered 
in pool 


Command line 
is buffered 
in pool 


Offspring 


Control Block 


(OCB) is 
created in 
pool 


Only OCB 
is in pool 


receive status 


again 
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of Data 


Notes 


Both tasks must 
be written to 
use Send/Receive 
directives 


Used with any 
task which uses 
GETMCR directive 
or Get Command 
Line (GCML) 
routine 


No separate 
directive 
needed in 
parent to 
receive status 


Any exiting task 
automatically 


data 
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Other Methods of Transferring or Sharing Data Between Tasks 


If large amounts of data are to be transferred between tasks or 
shared between tasks, two other techniques are available. Tasks 
can use files on mass’ storage devices, This technique is 
advantageous if really quick transfer is not essential and/or if a 
permanent copy of the data is desired. 


Tasks can also be written to share a data area in memory. This 
technique is particularly useful if transfer time is critical and 
a permanent copy of the data is either not needed at all or is not 


needed until a later time. Both of these techniques are discussed 
in later modules. 


Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all lab problems. Check your answers against the 
solutions provided, either in that book or in on-line files. 


If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress. 
Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, return 
to this module for further study. 
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MEMORY MANAGEMENT CONCEPTS 


INTRODUCTION 


The use of memory management hardware in mapped systems permits 
the use of more physical memory, task relocation, and the sharing 
of data and code. It also offers a memory protection feature. 
This module explains how the memory management hardware works and 
how the software interacts with the hardware. Later modules 


explain the use of memory management for overlays and shared 
regions. 


OBJECTIVES 


1. To list the differences between mapped and unmapped 
systems 


2. To list the advantages of memory management 


3. To use virtual and physical addresses, windows, and 
regions to describe the mapping of a task. 


RESOURCES 
1. RSX-11M/M-PLUS Task Builder Manual, Chapter 2 


2. PDP-11 Processor Handbook, Chapter 6 (optional) 
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GOALS OF MEMORY MANAGEMENT 


The KT~1l memory management unit is a device available on medium 
and larger PDP-1ll's. While the 16-bit addressing structure of the 
PDP-1ll's limits processors without a memory management unit to 32K 
words of addressing, processors with a memory management unit can 
Support up to 128K words, or even as much as 28@@K words (2 Meg 
words), depending on the model of the processor. 


In addition to this extension of the processor's addressing space, 
a memory management unit offers other features not otherwise 
available. With memory management, tasks can be loaded and 
executed at different locations in memory without being modified 
in any way. This means that the operating system can load a_ task 
into any available space within a system-controlled partition; 
therefore a task need not wait until a specific location is 
available. It also means that the Executive can move tasks around 
to make better use of available space (shuffling). 


Memory management also provides a mechanism for controlling tasks' 
access to memory. Memory areas can be protected: unrelated tasks 
can reside in memory simultaneously and are normally prevented 
from accessing each other's memory. However, tasks which do need 
to Share memory locations are allowed to do so, under the rules of 
memory access built into the Executive. 


HARDWARE CONCEPTS. 


Mapped Versus Unmapped Systems 


A system which has the KT-1l memory management unit installed and 
enabled is called a mapped system. Otherwise, it is called an 
unmapped system. Small PDP-ll's, such as the PDP-11/83 and 
PDP-11/84 are always unmapped. The KT-11l unit is available as an 
option on some medium sized processors, including the PDP-~11/35 
and PDP-11/4@. It is a Standard feature on large and newer 
processors such as the PDP-11/78, PDP-11/24, PDP-11/23-PLUS and 
PDP-11/44. | 


Table 5-1 shows a comparison of unmapped and mapped systems on 
various PDP-1ll's. 
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Table 5-1 Mapped Versus Unmapped Systems 


Memory Other Addressing 
System Addressing Size Addressing Limit 
Unmapped 16-bit 28K words I/O page 177777 
(56K bytes) 4K words 32K words 
(8K bytes) (64K bytes) 
Mapped 18-bit 124K words I/O page 777777 
(248K bytes) 4K words 128K words 
(8K bytes) (256K bytes) 
Mapped 22-bit 192@K words I/O page 17777777 
(3840K bytes) 4K words 2848K words 
(8K bytes) (4896K bytes) 
UNIBUS map 
124K words 


(248K bytes) 


Figures 5-1 to 5-3 show physical 
systems. Appendix 


address space on the various 
B contains a conversion chart between decimal 


and octal, 
helpful as 


Figure 5=1 


and between various word and byte values, which may be 
you read this module. 


Sixteen-bit 


shows the layout of an unmapped 
are all that are allowed. 

addressing limit of 32K words or 64K bytes. Of this, 28K words 
correspond to actual physical memory and 4K words correspond to 
the I/O page. The addresses in the I/0 page are assigned to 
peripheral devices which are used in performing I/O operations. 
On an RSX-11M system, the Executive, including the Dynamic Storage 
Region (DSR or POOL), takes up something less than or equal to 20K 


system. 


addresses This corresponds to an 


words (as little as 8K words). Tasks occupy the area between the 
top of the Executive and the top of memory. 
Figure 5-2 shows the layout of a mapped system with 18-bit 


addressing. Eighteen bits give an addressing limit of 128K words 


or 256K bytes. Again, the top 4K words correspond to the I/O 
page, leaving 124K words of physical memory. The Executive, 
including POOL, usually takes either 16K words or 2@K words, 


leaving the rest, either 188K words or 194K words, for tasks. 


166 


MEMORY MANAGEMENT CONCEPTS 


Figure 5-3 shows the layout of a mapped system with 22-bit 
addressing. Twenty-two bits give an addressing limit of 2948K 
words or 4@96K bytes. Again, the top 4K words correspond to the 
I/O page. 124K words are used for UNIBUS mapping, which is needed 
when peripheral devices access memory directly (DMA devices). 
UNIBUS mapping is necessary to convert 18-bit UNIBUS addresses .to 
22-bit physical memory addresses. This leaves 192@K words of 
physical memory. Again, the Executive, including POOL, usually 
takes 16K words or 2@K words, leaving 19@4K words or 198@K words 
for tasks. 


PHYSICAL 
ADDRESSES 
(IN OCTAL) 


177777 
4K WORDS 1/0 PAGE 


160000 
157777 


32K WORDS 
(28-N)K WORDS : OF ADDRESSING 
28K WORDS 
OF 
MEMORY 
N K WORDS 
(N<20) EXECUTIVE 


TK-7747 


Figure 5-1 Physical Address Space in an Unmapped System 
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PHYSICAL 
ADDRESSES 
(IN OCTAL) 
| . 777777 
4K WORDS | 1/0 PAGE 
760000 
757777 
108K OR 
104K WORDS 128K WORDS 
124K WORDS OF ADDRESSING 
OF 
MEMORY 
16K OR 20K 
WORDS EXECUTIVE 


TK-7757 


Figure 5-2 Physical Address Space in an 18-Bit Mapped System 
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PHYSICAL 
ADDRESSES 
(IN OCTAL) 
17777777 
4K WORDS 1/0 PAGE 
17760000 
17757777 
RESERVED 
124K WORDS 
(UNIBUS MAP) 
17000000 
16777777 
2048K WORDS 
1920K ican OF ADDRESSING 
WORDS OF 1900K WORDS 
MEMORY 
16K OR 20K 
WORDS EXECUTIVE 
0 


TK-7758 


Figure 5-3 Physical Address Space in a 22-Bit Mapped System 
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Virtual and Physical Addresses 


Virtual addresses are used within a task itself. They are always 
16-bit addresses in the range @(8) to 177777(8), or 32K words. 
When a task is task-built, virtual addresses are assigned 
typically starting at @(8) at the beginning of the task. 


Physical addresses are used in physical memory, the I/O page, and, 
with 22-bit systems only, the UNIBUS map. They begin with @(8) at 
the beginning of memory and include all of physical memory, the 
UNIBUS map, and the I/O page. 


On an unmapped system, no address’ relocation is’ performed. 
Therefore, virtual addresses match physical addresses. Figure 5-4 
Shows a task's virtual addresses and the corresponding physical 
addresses in an unmapped system. The task is loaded beginning at 
physical address 690900(8), and addresses referenced in the task 
code reference physical addresses directly. 


On a mapped system, the memory management hardware translates or 
"maps" a task's virtual addresses to the physical addresses in 
physical memory where the task is actually loaded. In the 
simplest case, the virtual addresses are offsets from a base 
physical address where the task is loaded... If a task is later 
relocated to another location in physical memory, the virtual 
addresses are then offset from the new base physical address. 


Figure 5-5 shows a task loaded at two different locations. As 
Shown below, at time 1, virtual address 1534(8) in the task is at 
the location 425134(8) in physical memory. At time 2, virtual 
address 1534(8) in the task is at location 141534(8) in physical 
memory. Since all addresses are converted at execution time, 
references to location 1534(8) in the task are resolved correctly 
regardless of where the task is loaded in physical memory. 


2434800(8) Base physical address 
1534(8) Offset (task virtual address) 


425134(8) Actual physical address 


1400008(8) Base physical saaress: 
1534(8) Offset (task virtual Address) 


141534(8) Actual physical address 
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On a mapped system, the Task Builder fixes a task's code in 
virtual address space, but the actual mapping of virtual addresses 
to physical addresses is performed at run time by the memory 
management unit. Tasks may be loaded at different physical 
addresses and still run correctly. As you will see later, mapping 
also allows a task to access several separate pieces of physical 
memory. 
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Figure 5-4 Virtual Addresses Versus Physical Addresses 
on an Unmapped System 
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Figure 5-5 Virtual Addresses Versus Physical Addresses 
on a Mapped System 
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The KT-11 Memory Management Unit 


Mode Bits - Bits 15 and 14 and bits 13 and 12 of the processor 
status word (PSW) indicate, respectively, the current and previous 
modes of processor operation. The mode may be: 


e Kernel mode (@@) 
e User mode (11) 


e Supervisor mode (@1). (Supervisor mode is not used on 
RSX-11M, and is available only on 11/45, 11/55, 11/44, and 
11/70.) 


The purpose of having different processor modes is to provide for 
a privileged mode (kernel) where the Executive can execute 
privileged instructions (e.g., HALT), and can manipulate 
privileged locations (e.g., PSW), and a non-privileged and 
protected mode (user) where tasks usually execute. 


Active Page Registers (APRs) - The Active Page Registers (APRs) in 

the KT-1l memory management unit are used to define the mapping or 
correspondence between virtual and physical addresses. On an 
RSX-11M system, one set of eight APRs is used at a time to define 
this mapping. There is one set of APR's used for each processor 


mode; one is used in user mode and another set is used in kernel 
mode. 


At any given time, the set of APRs in use is determined by the 
mode bits in the processor status word. Each APR in the set in 
use maps a specific range of virtual addresses, as shown in Table 
5-2. The APR can map zero words, if not in use, up to the full 4K 
words, always in even multiples of 32 words. In actuality, the 
hardware may contain additional sets of APRs, but they are not 
used under RSX-11M. 


Each APR consists of two 16-bit registers, a page address register 
(PAR) and a page descriptor register (PDR). The page address 
register contains a base address used in mapping the appropriate 
range of virtual addresses. 
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Table 5-2 APR and Virtual Address Correspondence 


APR Virtual Address 

Number Range | K Words 
7 169880-177777 (8) 28-32K 
6 149908-157777 (8) 24-28K 
5 129898-137777 (8) 26-24K 
4 188988-117777 (8) 16-20K 
3 69088- 77777 (8) 12-16K 
2 49900- 57777(8) 8-12K 
d: 28998- 37777(8) 4— 8K 
i) @- 17777(8) @- 4K 


Because the page address register contains only 16 bits, but the 
actual physical addresses on the larger PDP-11's contain 18 or 22 
bits, the 16 bits cannot contain an actual physical address. 
Instead, the 16 bits contain a block number, which corresponds to 
the high-order 16 bits (12 bits with 18-bit addressing) of the 
actual physical address. A block of memory is 32(18) words (= 
64(109) bytes = 198(8) bytes) long and starts on a 199@(8) boundary. 
Therefore, the base physical address §9@134200(8) is the start of 
block number 9@1342(8) and the base address 12445790(8) is the 
start of block number 124457(8). | 


To obtain the block number from a physical address which ends in 
at least two octal zeros, just strip off the last two zeros from 
the actual address. To obtain the physical address from the block 
number, append two zeros to the end of the block number in octal. 


The page descriptor register (PDR) contains information about’ the 
page of memory in use, such as the length of the page (up to 4K 
words) and the access rights (read/write, read-only, etc.). The 
fields for length and access rights in the PDR provide the 
capability for hardware memory protection. If any reference in a 
task is beyond the actual area in use or violates the access 
rights, a memory protect violation is reported. 


For a more complete description of the PARS and the PDRs, see 
Chapter 6 of the PDP-1ll Processor Handbook. 


Figure 5-6 shows the values in the page address registers for an 
example task. The main part of the task is 14K words long; 
therefore it needs four APRs; three APRs (APR 9,1, and 2) mapping 
4K words each, and a fourth APR (APR3) mapping the last 2K words. 
The base physical address of the task is 9@432400(8), which is 
obtained by converting the block number @84324(8) to a byte 
address. . 
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All virtual addresses within the main task area are mapped to 
physical addresses beginning at location 98432480(8). This means 
in effect that each virtual address corresponds to an offset from 
location G0432400(8). The page descriptor registers, not 
illustrated, indicate that APRs @, 1, and 2 map 4K words each, but 
that APR 3 maps only 2K words. | 
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MEMORY ADDRESSES 
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Figure 5-6 Page Address Registers Used in Mapping a Task 
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The task in Figure 5-6 is also mapped to a resident common. APR 7 
is used to map this 4K word area,,.beginning at location 9153200(8) 
in physical memory. Therefore, virtual addresses from 169980(8) 
to 177777(8) map to physical addresses @1532200(8) to 91732177(8). 
Virtual address 1653414(8) corresponds’ to physical address 
@1532200(8) + [1653414(8)-1698000(8)] = 91605614(8). 


Note that a task can be loaded into a minimum of one or a maximum 
of eight separate contiguous areas of memory, because each APR 
must map to a contiguous area of memory. If a 32K word task is 
loaded into one large contiguous area, eight APRs are still used, 
but each APR maps only part of the large contiguous area. 


Converting Virtual Addresses to Physical Addresses 


The following two examples show how the KT-11l memory management 
unit converts virtual addresses to physical addresses for the task 
Shown in Figure 5-6. 


Example 1 


The KT-1l1l unit takes a virtual address and uses the value in the 
appropriate APR to convert it to a physical address. The virtual 
address range indicates which APR to use (Table 5-2). 


Since 953422(8) is in the range 948000-057777, APR 2 is used. Or, 
looking at the address in binary, the high-order three bits 
indicate which APR to use. Bits @ through 12 indicate’ the 
displacement or offset from the base physical address of the page. 
This is equal to @53422(8) - #@40000(8) = 13422(8), the distance of 
this virtual address from the base virtual address for this APR. 


Active 

Page Displacement 

Field Field 
+------- 4---------—------------------ + 

@53422(8) = |8@16{1161141680186008186 | (2) 
+------- 4-----~---------------------- + 
2 13422 (8) 
APR Offset 
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In easier terms, virtual address 49000(8) will be located at the 
base physical address. A virtual address 13422(8) bytes above 
that will be 13422(8) bytes above that physical location. The 
base physical address is determined by converting the block number 
in APR2, @84724(8), to the physical address 98472400(8). (Recall 
that a block of memory is 190(8) bytes.) Therefore, address 
953422(8) is mapped to the location shown below. 


@8472408(8) Base physical address 
+ 13422(8) Displacement 


$0586022(8) Actual physical address 


Example 2 


Convert the virtual address 165275(8) 


+------- $--------------------------- + 
165275(8) = 111412141064316018018081d1d212d186i21 4 (2) 
+------- $--------------------------- + 
7 95275 (8) 
APR Offset 


APR 7 = @15322(8) blocks = 915322808(8) Base physical address 
. + 95275(8) Displacement 


— me ee ee ee ee we ee es oe ow 


$1537475(8) Actual physical address 


The memory management unit performs this conversion using an adder 
and a number of internal registers. The conversion is performed 
at extremely fast speeds. Chapter 6 of the 
PDP-1l1l Processor Handbook discusses this conversion process in 
more detail. 
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SOFTWARE CONCEPTS 


Virtual Address Windows 


A virtual address window, or simply a window, is a _ contiguous 
range of virtual addresses within a task. -A window is always 
mapped as a unit, to a contiguous range of physical locations. A 
task which resides in a single contiguous area of physical memory 
generally has a single window, called the task window, which is 
mapped to the area. An example of this was shown in Figure 5-5, 
which has a single window 24K words long. Notice that the window 
is the same at time 1 and time 2, but it maps to different 
locations in physical memory. On the other hand, a task which 
must access two separate pieces of physical memory at the same 
time would have two windows (as in Figure 5-6) to map those areas. 


Windows are mapped using APRs. A virtual address window always 
corresponds to at least one, but possibly more than one, APR (up 
to all eight). A window always begins at a 4K word boundary, 
corresponding to the lowest address mapped by the first APR used 
for the window. Successively higher APRs are then used, until the 
entire window is’ provided for. The Task Builder assigns most 
virtual addresses and creates most windows, determining which APRs 
will be used during that task's execution. 


The task window for a task begins at virtual address @ (therefore 
using APR @) and extends upward as far as necessary to accommodate 
the task's header, stack, main code and data. Other windows’ can 
begin at any 4K word boundary above the high limit of the task 
window. Typically, additional windows are assigned from the _ top 
of virtual address space working downwards. For example, if an 
additional address window of 4K words or less is needed, it is 
assigned a base address of 169880(8), using APR 7. 


If, on the other hand, a window is needed between 4K words and 8K 
words in size, the window will be given ae base address of 
149000(8). In this case, the window. would use APRS 6 and 7. 
Additional windows would be assigned lower base addresses that 
correspond to other available APRs. 


NOTE 
Under no circumstance can two windows’ exist 
at the same time within a task using the same 
APR or the same virtual addresses. 
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The Task Builder allocates space in the task header for’ the 
windows it has created and records information that specifies how 
these windows are to be mapped. This information is used to load 
the APRs with appropriate values before the task executes. 


Memory management directives can be used to create and initialize 
additional windows while a task executes. Space for’ these 
additional windows must be allocated in the task header at 
task-build time, using the "WNDWS" option. Memory management 
directives and their use are discussed in Module 8 on Dynamic 
Regions. 


Regions 


A region is a contiguous area of physical memory to which a_e task 
may get access’ rights. A region must be contained completely 


within a partition. It can be part of a partition or the entire 
partition. 


There are three types of regions in an RSX-11M system. 


l. Task region - an area in a user-controlled partition or a 
system-controlled partition into which a task is loaded 
and then executes. 


2. Static Common Region - an area in a common type partition; 
e.g., a shared common for data or a shared library for 
code. 


3. Dynamic Region - an area in a system-controlled partition 
which is created dynamically, at run time, using the 
memory management directives. 


A task gets access rights to a region by "attaching" to the 
region. Before the Executive attaches a task to a region, it 
checks its needed access against the protection on the region. 
This is similar to checking file protection before allowing file 
access. If the task passes the check on access rights, then the 
Executive attaches the task to the region by establishing a 
connection between the two. The total amount of physical memory, 


made up of regions, to which a task is attached is called a task's 
logical address space. 
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After a task is attached to a region, it actually accesses or uses 
the region by first "mapping" one of its virtual address windows 
to a part or to all of the _ region. During this process, the 
Executive uses the window and region information to fill in the 
APRs. After this, references in the task to virtual addresses in 
that window map to physical addresses within the region. A region 
does not have to be the same size as a window. Generally it is of 
equal or larger size than the window. 


Attaching and mapping are done automatically by the Executive for 
regions linked to at task-build time. Alternatively, a task can 
use memory management directives at run time to dynamically create 
regions, attach to regions, and map windows to regions. 


Figure 5-7 shows a task which has three virtual address windows 
mapped to three different regions. Figure 5-8 shows the same task 
after it attaches to another region (the work area) and maps- to 
it. Notice that virtual addresses beginning at 1990000(8) are used 
to map this region. For example, this area might be used as a 
temporary work buffer. Figure 5-8 does not include the actual PAR 
values or the actual physical addresses. This simpler form of 
mapping diagram will be used from now on in this course to make 
things easier, unless the actual PAR values and physical addresses 
are significant to the discussion. 


Now do the tests/exercises for this module in the Tests/Exercises 
book. They are all written problems. Check your answers against 
those provided in that book. 


If you think that you have mastered the material, ask your course 
administrator to record your progress in your Personal Progress 
Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, return 
to this module for further study. 
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Figure 5-7 A Task with Three Windows Mapped to Three Regions 
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